@precisionutilityguild/liquid-shadow 1.0.9 → 1.0.10

package/dist/web-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.9",
+  "version": "1.0.10",
   "toolsByPrefix": {
     "RECON": {
       "subcommands": [
@@ -50,6 +50,8 @@
         "release",
         "synthesize",
         "track",
+        "tribunal_status",
+        "tribunal_submit",
         "working_set_check"
       ],
       "description": "Create a new development mission or strategic initiative with goals and strategy."
@@ -90,18 +92,23 @@
     {
       "slug": "shadow_audit",
       "name": "AUDIT",
-      "description": "Perform codebase health audits to identify dead code, circular dependencies, and technical debt. Use when auditing code quality, finding unused code, detecting circular dependencies, or when the user asks about codebase health, technical debt, or code cleanup."
+      "description": "Audit repository health with Shadow tools. Use when hunting dead code, import cycles, layer drift, orphaned config, structural risks, or when turning audit findings into cleanup work."
     },
     {
       "slug": "shadow_chronicle",
       "name": "CHRONICLE",
-      "description": "Retrieve and analyze the repository's narrative archive as recorded in Git-native memory. Use when you need to understand historical decisions, catch up on repository progress, review recently completed missions, or when the user asks for a project history, changelog, or chronological overview of architectural changes."
+      "description": "Read the repository narrative archive. Use when you need project history, ADR context, recent completed work, release-note material, or a chronological view of architectural changes."
     },
     {
       "slug": "shadow_continue",
       "name": "CONTINUE",
       "description": "Get briefing, pick one mission from next_work_candidates, then work that mission to completion with all remaining steps in one run. Use when continuing work on missions, executing mission steps, or when the user asks to continue work, finish a mission, or proceed with development tasks."
     },
+    {
+      "slug": "shadow_coordinate",
+      "name": "COORDINATE",
+      "description": "Coordinate multi-agent or parallel work with working-set checks, file claims, dispatch waves, handoffs, and user-approved Tribunal review. Use when several agents may edit at once or when work must be transferred cleanly."
+    },
     {
       "slug": "shadow_crystallize",
       "name": "CRYSTALLIZE",
@@ -110,17 +117,17 @@
     {
       "slug": "shadow_mission",
       "name": "MISSION",
-      "description": "Define the objective, strategy, and success criteria for a new development mission. Use when planning strategic initiatives, creating missions, setting up development goals, or when the user asks about mission planning, strategic alignment, or outcome contracts."
+      "description": "Define the objective, strategy, and success criteria for a mission. Use when planning new work, shaping initiatives, writing outcome contracts, or aligning a task before execution starts."
     },
     {
       "slug": "shadow_onboard",
       "name": "ONBOARD",
-      "description": "Initialize and analyze a new repository for deep intelligence by building semantic index, syncing state, activating git hooks, and establishing missions. Use when onboarding to a new repository, initializing Shadow Engine, setting up git hooks, or when the user asks about repository setup, initialization, or first-time configuration."
+      "description": "Initialize and analyze a repository for Shadow workflows. Use when onboarding a repo, bootstrapping indexes and hooks, checking intelligence health, or preparing the first mission."
     },
     {
       "slug": "shadow_research",
       "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."
     },
     {
       "slug": "shadow_sync",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@precisionutilityguild/liquid-shadow",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Tactical Repository Intelligence Operative - Liquid Shadow Ecosystem",
   "homepage": "https://liquidshadow.pugcorp.online/",
   "repository": {

package/skills/shadow_audit/SKILL.md

@@ -1,43 +1,35 @@
 ---
 name: audit
-description: Perform codebase health audits to identify dead code, circular dependencies, and technical debt. Use when auditing code quality, finding unused code, detecting circular dependencies, or when the user asks about codebase health, technical debt, or code cleanup.
+description: Audit repository health with Shadow tools. Use when hunting dead code, import cycles, layer drift, orphaned config, structural risks, or when turning audit findings into cleanup work.
 ---
 
-# Codebase Audit
+# Audit
 
-Comprehensive health audit using Shadow analyze toolkit.
+Use this skill when the goal is repository health, not feature delivery.
 
-## 🚀 Workflow
+## Start
 
-1. **Session Context**: `shadow_ops_context` (repoPath) — **ONE CALL** for hologram + chronicle + briefing. Get architecture baseline.
-2. **Dead Code Detection**: `shadow_analyze_debt` (mode: "dead-code", limit: 100, includeTests: false, repoPath) — Unused exports.
-3. **Circular Dependencies**: `shadow_analyze_debt` (mode: "circular-deps", limit: 20, repoPath) — Import cycles.
-4. **Layer Integrity** (optional): `shadow_recon_topography` (repoPath) — Detailed layer analysis if hologram summary isn't enough.
-5. **Log Findings**: `shadow_ops_log` (missionId, type: "discovery", content, repoPath).
-6. **Create Cleanup Mission** (optional): `shadow_ops_plan` (name: "Codebase Cleanup", templateId: "refactoring", templateVars, repoPath).
+1. `shadow_ops_context({ repoPath, compact: true })`
+2. `shadow_analyze_debt({ repoPath, mode: "dead-code", confidenceThreshold: "high" })`
+3. `shadow_analyze_debt({ repoPath, mode: "circular-deps" })`
 
-## 🛠 Precise Tooling
+## Add depth only when needed
 
-| Audit Target         | Atomic Tool                                                                            |
-| :------------------- | :------------------------------------------------------------------------------------- |
-| **Session Start** 🚀 | `shadow_ops_context` (repoPath) — **START HERE** for baseline                          |
-| **Architecture**     | `shadow_recon_hologram` (repoPath) — if you need standalone                            |
-| **Dead Code**        | `shadow_analyze_debt` (mode: "dead-code", limit: 100, **confidenceThreshold: "high"**) |
-| **Circular Deps**    | `shadow_analyze_debt` (mode: "circular-deps")                                          |
-| **Layers**           | `shadow_recon_topography` — detailed breakdown if needed                               |
-| **Config Audit**     | `shadow_search_config` (kind: "Env", **showUsage: true**) — find orphaned env vars     |
-| **Event Mesh**       | `shadow_analyze_mesh` (repoPath) — audit all HTTP routes, socket events, pubsub topics |
-| **Type Integrity**   | `shadow_analyze_type_graph` (filePath, repoPath) — interface/type inheritance chains   |
-| **Theme Patterns**   | `shadow_ops_crystallize_theme` (query, repoPath) — recurring issues across missions    |
+- `shadow_recon_topography({ repoPath })` for layer drift and boundary violations.
+- `shadow_recon_scout({ repoPath })` for architectural drift and anomalies.
+- `shadow_search_config({ repoPath, kind: "Env", showUsage: true })` for orphaned config and env keys.
+- `shadow_analyze_impact({ repoPath, symbolName, filePath? })` for risky hubs.
+- `shadow_analyze_type_graph({ repoPath, symbolName, filePath? })` when a central interface or base class is involved.
+- `shadow_analyze_mesh({ repoPath, topic, type? })` only when you already have a concrete route or event fragment such as `"/api/"` or `"order."`.
 
-## 💡 Intelligence Options
+## Close the loop
 
-- **`shadow_analyze_debt` confidence levels**: Use `confidenceThreshold: "high"` for likely dead code, `"medium"` for possibly intentional (test fixtures, etc.), `"all"` for everything.
-- **`shadow_analyze_debt` exclusion filters**: Use `excludePatterns`, `includeMigrations: false`, `includeFixtures: false` to reduce noise.
-- **`shadow_search_config` with `showUsage: true`**: Cross-references config vars with code to show usage counts and identify orphaned vars (defined but never used).
+- `shadow_ops_log({ repoPath, missionId?, type: "discovery", content, filePath?, symbolName? })`
+- `shadow_ops_handoff({ repoPath, missionId?, kind: "debt_scan", findings, risks?, gaps? })`
+- `shadow_ops_plan({ repoPath, name, goal, templateId: "refactoring", workingSet? })`
 
-## 🔍 Health Criteria
+## Rules
 
-- **Critical Issues**: Circular deps in core logic, >50 dead exports, orphaned env vars with secrets
-- **Warning Signs**: Layer violations (Test → Logic), >20 dead exports, >10 orphaned configs
-- **Good Health**: Clean layers, <10 dead exports, no circular deps, all configs in use
+- Start with `confidenceThreshold: "high"` and widen only if the user wants a broader sweep.
+- `shadow_ops_crystallize_theme` takes `theme`, not `query`.
+- `shadow_analyze_type_graph` requires `symbolName`.

package/skills/shadow_chronicle/SKILL.md

@@ -1,40 +1,27 @@
 ---
 name: chronicle
-description: Retrieve and analyze the repository's narrative archive as recorded in Git-native memory. Use when you need to understand historical decisions, catch up on repository progress, review recently completed missions, or when the user asks for a project history, changelog, or chronological overview of architectural changes.
+description: Read the repository narrative archive. Use when you need project history, ADR context, recent completed work, release-note material, or a chronological view of architectural changes.
 ---
 
-# Repository Chronicle
+# Chronicle
 
-Retrieve narrative archive from Git-native memory.
+Use this skill when the answer lives in mission history rather than the current code graph.
 
-## 🚀 Workflow
+## Core calls
 
-1. **Recent History**: `shadow_ops_chronicle` (limit: 10, format: "markdown", repoPath) — Last 10 entries.
-2. **Time-Filtered**:
-   - `shadow_ops_chronicle` (since: <unix>, limit: 20, repoPath)
-   - `shadow_ops_chronicle` (until: <unix>, limit: 20, repoPath)
-3. **Structured Data**: `shadow_ops_chronicle` (format: "json", limit: 50, repoPath) — For processing.
-4. **Paginated**: `shadow_ops_chronicle` (limit: 10, offset: 10, repoPath) — Second page.
+- Recent narrative: `shadow_ops_chronicle({ repoPath, limit: 10, format: "markdown" })`
+- Structured output: `shadow_ops_chronicle({ repoPath, format: "json", limit: 50 })`
+- Time window: `shadow_ops_chronicle({ repoPath, since, until })`
+- Branch-scoped history: `shadow_ops_chronicle({ repoPath, branch, limit })`
+- Pagination: `shadow_ops_chronicle({ repoPath, limit, offset })`
 
-## 🛠 Precise Tooling
+## Good pairings
 
-| Chronicle Query       | Atomic Tool                                                       |
-| :-------------------- | :---------------------------------------------------------------- |
-| **Recent (Markdown)** | `shadow_ops_chronicle` (limit: 10, format: "markdown")            |
-| **Time Range**        | `shadow_ops_chronicle` (since: <unix>, until: <unix>) |
-| **JSON Data**         | `shadow_ops_chronicle` (format: "json", limit: 50)                |
-| **Pagination**        | `shadow_ops_chronicle` (limit: 10, offset: 10)                    |
+- `shadow_ops_context({ repoPath, compact: true })` if you also need the current mission landscape.
+- `shadow_ops_graph({ repoPath, missionId, format: "mermaid" })` when a historical mission hierarchy matters.
 
-## Output Formats
+## Notes
 
-- **`format: "markdown"`** (default): Human-readable narrative feed with missions grouped as Strategic Initiatives and Standalone Episodes
-- **`format: "json"`**: Structured data for programmatic analysis (includes missionId, steps, timestamps, ADRs)
-
-## Use Cases
-
-- **Onboarding**: Read last 10 entries to catch up
-- **Release Notes**: Get completed missions since last release
-- **ADR Review**: Extract all architectural decisions
-- **Progress Reports**: Show what's been done this week
-
-**Note:** Chronicle reads from Git Notes, so it's persistent across branches and clones.
+- `format: "markdown"` is best for humans.
+- `format: "json"` is best when another tool or agent will process the result.
+- Chronicle is backed by Git Notes, so it survives across branches and clones.

package/skills/shadow_continue/SKILL.md

@@ -3,61 +3,45 @@ name: continue
 description: Get briefing, pick one mission from next_work_candidates, then work that mission to completion with all remaining steps in one run. Use when continuing work on missions, executing mission steps, or when the user asks to continue work, finish a mission, or proceed with development tasks.
 ---
 
-**In one sentence:** Get briefing (+ optional trace), pick **one mission** from **next_work_candidates** (ranked by relevance), then work that mission to completion — all remaining steps in one run. Update and log as you go. No status reports; when you're done with that mission, it's done.
+# Continue
 
----
+Pick one mission from `next_work_candidates` and finish it end to end.
 
-## 1. Context
-
-- **Option A (one shot):** `shadow_ops_context` (repoPath) → returns hologram + chronicle(5) + **briefing** (counts, **next_work_candidates** ranked by relevance). Use when you want architecture + history + backlog in one call at the start of /continue.
-- **Option B:** `shadow_ops_briefing` (scope: "project", repoPath) → **next_work_candidates** (relevance-ranked), hierarchy, analytics.
-  - Use **altitude** to control output density: `orbit` (~200 tokens, counts + candidates only), `atmosphere` (default, strategy + crystals), `ground` (raw logs + working set + collisions).
-- `shadow_sync_trace` (repoPath) only if you care about external changes. Otherwise skip.
-
-## 2. Pick one mission
-
-- **`next_work_candidates`** are ranked by the MissionRelevanceScorer (recency × 0.4 + activity × 0.3 + status × 0.2 + blockers × 0.1). Higher score = more relevant.
-- Choose the top-ranked candidate. Prefer in-progress over planned. Parent-only missions (umbrellas) are already filtered out.
-
-## 3. Work the whole mission
-
-- For that mission, run through **all remaining steps** (not just one):
-  - **Surgical Discovery:** `shadow_analyze_flow` (symbolName, filePath, repoPath).
-  - **Execute Step**: Set in-progress → implement → `shadow_ops_track` (missionId, stepId, status: "completed", contextPivot, repoPath).
-  - **Atomic Logging:** At least once per step. `shadow_ops_log` (missionId, type: "decision", content, symbolName, repoPath).
-  - **Inter-agent handoff** (multi-agent pipelines only): When handing off findings to another agent, call `shadow_ops_handoff` (missionId, role, summary, findings, repoPath) to persist a typed artifact with embedding. The receiving agent calls `shadow_ops_handoff_read` (missionId, query, repoPath) to semantically retrieve relevant prior handoffs.
-- **Seal the mission**: `shadow_ops_track` (missionId, status: "completed", repoPath).
-  - This **auto-triggers**: ADR synthesis, Git Notes persistence, and cascade parent completion (if all sibling missions are also done, the parent auto-completes too).
-  - No need to call `shadow_ops_synthesize` separately — it's automatic on completion.
-- **Optional — Crystallize** (for long-running missions with many logs): `shadow_ops_crystallize` (missionId, repoPath) compresses raw intent logs into a single crystal summary. Useful mid-mission to keep briefings lean.
-- **Optional — Theme Crystallize** (cross-mission patterns): `shadow_ops_crystallize_theme` (query, repoPath) clusters semantically related intent logs across ALL missions to surface recurring architectural themes. Use when you sense a pattern repeating across missions.
-
-## 🛠 Precise Tooling
-
-| Action                 | Atomic Tool                    | Example                                                          |
-| :--------------------- | :----------------------------- | :--------------------------------------------------------------- |
-| **Context (one shot)** | `shadow_ops_context`           | repoPath — hologram + chronicle + briefing                       |
-| **Briefing**           | `shadow_ops_briefing`          | scope: "project", altitude: "orbit", repoPath                    |
-| **Flow Trace**         | `shadow_analyze_flow`          | symbolName: "handleRequest", filePath, repoPath                  |
-| **Step Update**        | `shadow_ops_track`             | missionId: 4, stepId: "s2", status: "completed"                  |
-| **Intent Log**         | `shadow_ops_log`               | missionId: 4, type: "fix", content: "..."                        |
-| **Complete Mission**   | `shadow_ops_track`             | missionId: 4, status: "completed" — auto-synthesizes ADR         |
-| **Crystallize**        | `shadow_ops_crystallize`       | missionId: 4 — compress logs mid-mission                         |
-| **Theme Crystallize**  | `shadow_ops_crystallize_theme` | query: "auth patterns" — cross-mission semantic clustering       |
-| **Handoff (write)**    | `shadow_ops_handoff`           | missionId, role: "RECON", summary, findings — persist artifact   |
-| **Handoff (read)**     | `shadow_ops_handoff_read`      | missionId, query: "auth findings" — semantic retrieval           |
-| **Event Mesh**         | `shadow_analyze_mesh`          | repoPath — surface all HTTP routes, socket events, pubsub topics |
-| **Type Graph**         | `shadow_analyze_type_graph`    | filePath, repoPath — interface/type inheritance map              |
-| **Explain Diff**       | `shadow_analyze_explain_diff`  | fromCommit, toCommit, repoPath — semantic diff narrative         |
-
-_Note: Always use `symbolName` in `shadow_ops_log` to create Liquid Anchors._
-
-## 4. Don't
+## Start
 
-- Don't do one step and stop — /continue is "finish a mission," not "do one step."
-- Don't call `shadow_ops_synthesize` after completing — it's automatic on `status: "completed"`.
-- Don't long status reports. Don't ask "what should I work on?" unless a real tie. Don't auto-commit.
+1. `shadow_ops_context({ repoPath, compact: true })` or `shadow_ops_briefing({ repoPath, scope: "project", altitude: "orbit" })`
+2. Pick one leaf mission from `next_work_candidates`. Prefer in-progress over planned.
+3. If there is no candidate, stop and plan new work instead of inventing a mission.
 
----
+## Work loop
+
+- Mark the active step: `shadow_ops_track({ repoPath, missionId, stepId, status: "in-progress" })`
+- If multiple agents may edit the same area, check and claim first:
+  - `shadow_working_set_check({ repoPath, filePaths })`
+  - `shadow_ops_claim({ repoPath, missionId, filePaths, agentTag? })`
+- Do focused discovery with the relevant search, recon, analyze, and inspect tools.
+- Record at least one meaningful log per step:
+  - `shadow_ops_log({ repoPath, missionId, type: "decision" | "discovery" | "fix", content, filePath?, symbolName? })`
+- Mark each finished step:
+  - `shadow_ops_track({ repoPath, missionId, stepId, status: "completed", contextPivot? })`
 
-**Tools:** `shadow_ops_context` (optional start), `shadow_ops_briefing`, `shadow_ops_track`, `shadow_ops_log`, `shadow_ops_crystallize`, `shadow_ops_crystallize_theme`, `shadow_ops_handoff`, `shadow_ops_handoff_read`, `shadow_sync_trace`. For discovery: `shadow_search_*`, `shadow_recon_*`, `shadow_analyze_*` (including `shadow_analyze_mesh`, `shadow_analyze_type_graph`, `shadow_analyze_explain_diff`).
+## Finish
+
+- Optional handoff for downstream agents:
+  - `shadow_ops_handoff({ repoPath, missionId, kind, findings, risks?, gaps?, confidence?, agentTag? })`
+  - `shadow_ops_handoff_read({ repoPath, missionId?, kind?, query?, limit? })`
+- Optional review gate, but only after the user explicitly asks for Tribunal or clearly approves it:
+  - `shadow_ops_tribunal_submit({ repoPath, missionId })`
+  - `shadow_ops_tribunal_status({ repoPath, missionId })`
+- Release any claims you took:
+  - `shadow_ops_release({ repoPath, missionId, filePaths? })`
+- Complete the mission:
+  - `shadow_ops_track({ repoPath, missionId, status: "completed" })`
+
+## Rules
+
+- Don't do one step and stop — /continue is "finish a mission," not "do one step."
+- Don't call `shadow_ops_synthesize` after completion unless you are intentionally regenerating the record.
+- Never run Tribunal without explicit user consent.
+- `shadow_ops_handoff` does not take `role` or `summary`; use `kind` plus structured `findings`.
+- `shadow_ops_crystallize_theme` takes `theme`, not `query`.

package/skills/shadow_coordinate/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: coordinate
+description: Coordinate multi-agent or parallel work with working-set checks, file claims, dispatch waves, handoffs, and user-approved Tribunal review. Use when several agents may edit at once or when work must be transferred cleanly.
+---
+
+# Coordinate
+
+Use this skill when execution risk comes from overlap, not code complexity.
+
+## Conflict control
+
+- `shadow_working_set_check({ repoPath, filePaths })`
+- `shadow_ops_claim({ repoPath, missionId, filePaths, agentTag? })`
+- `shadow_ops_release({ repoPath, missionId, filePaths? })`
+
+## Parallel planning
+
+- `shadow_ops_dispatch_plan({ repoPath, parentMissionId?, missionIds?, includeClaimCheck: true })`
+- `shadow_ops_graph({ repoPath, missionId, depth?, format: "mermaid" | "json" })`
+
+## Handoffs
+
+- Write: `shadow_ops_handoff({ repoPath, missionId?, kind, findings, risks?, gaps?, missionsCreated?, confidence?, agentTag? })`
+- Read: `shadow_ops_handoff_read({ repoPath, missionId?, kind?, query?, limit? })`
+
+Available `kind` values:
+
+- `recon_report`
+- `risk_assessment`
+- `impact_map`
+- `debt_scan`
+- `custom`
+
+## Tribunal
+
+Never run Tribunal unless the user explicitly asks for it or clearly approves it.
+
+- `shadow_ops_tribunal_submit({ repoPath, missionId })`
+- `shadow_ops_tribunal_status({ repoPath, missionId? or sessionId? })`
+
+## Rules
+
+- Claim only the files you expect to edit.
+- Release claims promptly when the work is done.
+- Tribunal is opt-in only. Treat it as a user-consent gate, not an automatic review step.
+- Handoffs must be structured. There is no `role` or `summary` field.

package/skills/shadow_crystallize/SKILL.md

@@ -3,39 +3,25 @@ name: crystallize
 description: Compress a mission's intent logs into a dense crystal summary for token-efficient briefings. Use when a mission has accumulated many raw logs, when briefings are too verbose, or when the user asks about log compression, crystallization, or context reduction.
 ---
 
-# Intent Log Crystallization
+# Crystallize
 
-Compress raw intent logs into a single crystal summary node. The crystal replaces verbose raw logs in briefings, reducing token usage while preserving the mission's key decisions, context, and consequences.
+Compress raw intent logs into a crystal so briefings stay useful instead of noisy.
 
-## When to Crystallize
+## Core calls
 
-- A mission has **10+ raw intent logs** and briefings are getting verbose.
-- Mid-mission, before requesting a detailed briefing — keeps `atmosphere` altitude lean.
-- Before synthesis (optional) — produces cleaner ADRs from compressed input.
-- The briefing at `atmosphere` altitude already prefers crystals over raw logs (`findByMissionPreferCrystal`), so crystallizing makes those briefings significantly leaner.
+- Mission-level compression: `shadow_ops_crystallize({ repoPath, missionId })`
+- Verify the result: `shadow_ops_briefing({ repoPath, scope: "mission", missionId, altitude: "atmosphere" })`
+- Cross-mission theme compression: `shadow_ops_crystallize_theme({ repoPath, theme, missionIds?, limit? })`
 
-## Workflow
+## When to use it
 
-1. **Crystallize**: `shadow_ops_crystallize` (missionId, repoPath) — Compresses all raw logs into one crystal node. Raw logs are marked as `absorbed`.
-2. **Verify**: `shadow_ops_briefing` (scope: "mission", missionId, altitude: "atmosphere", repoPath) — Crystal should appear in `recent_activity` instead of raw logs.
-
-## Precise Tooling
-
-| Action           | Atomic Tool                                    | Usage                                   |
-| :--------------- | :--------------------------------------------- | :-------------------------------------- |
-| **Crystallize**  | `shadow_ops_crystallize`                       | missionId, repoPath — compress raw logs |
-| **Check Status** | `shadow_ops_briefing` (altitude: "atmosphere") | Verify crystal appears in activity      |
-| **Full Logs**    | `shadow_ops_briefing` (altitude: "ground")     | Still shows raw logs if needed          |
-
-## What the Crystal Contains
-
-- Mission name and ID
-- Count of compressed logs and symbols
-- Log types present (decision, fix, discovery, blocker)
-- Structured breakdown: decisions, context, consequences, recommendations
+- A mission has many raw logs and `atmosphere` briefings are getting bloated.
+- You want cleaner synthesis input before closing a mission.
+- You want to surface repeating patterns across missions with `theme`.
 
 ## Notes
 
 - Crystallization is **idempotent**: if no new raw logs exist, it reports `already_crystallized`.
-- New logs added after crystallization remain as raw until the next crystallize call.
-- Raw logs are **not deleted** — they're marked as absorbed. `ground` altitude still shows them.
+- Raw logs are not deleted; they are marked as absorbed.
+- New logs stay raw until the next crystallize call.
+- `shadow_ops_crystallize_theme` takes `theme`, not `query`.

package/skills/shadow_mission/SKILL.md

@@ -1,53 +1,39 @@
 ---
 name: mission
-description: Define the objective, strategy, and success criteria for a new development mission. Use when planning strategic initiatives, creating missions, setting up development goals, or when the user asks about mission planning, strategic alignment, or outcome contracts.
+description: Define the objective, strategy, and success criteria for a mission. Use when planning new work, shaping initiatives, writing outcome contracts, or aligning a task before execution starts.
 ---
 
-# Mission Strategy & Setup
+# Mission
 
-Define the objective, strategy, and success criteria for a new mission. This workflow is for **Strategic Alignment and Planning**.
+This skill is for planning. It stops at "ready to execute."
 
-> **IMPORTANT**: This workflow stops at the "Ready to Execute" state. For implementation and automated execution, use **/continue**.
+## Start
 
-## Workflow
+1. `shadow_ops_context({ repoPath, compact: true })`
+2. If needed, expand with:
+   - `shadow_recon_topography({ repoPath })`
+   - `shadow_ops_briefing({ repoPath, scope: "project", altitude: "ground" })`
+   - `shadow_ops_chronicle({ repoPath, limit: 10 })`
+3. Reuse prior intelligence when available:
+   - `shadow_ops_handoff_read({ repoPath, missionId?, kind?, query? })`
+   - `shadow_ops_crystallize_theme({ repoPath, theme, missionIds? })`
 
-1.  **Session Context**: `shadow_ops_context` (repoPath) — **ONE CALL** for hologram + chronicle(5) + briefing (with relevance-ranked `next_work_candidates`). Check existing candidates and recent decisions before creating new work.
-2.  **Optional Expanded Context** (only if needed):
-    - `shadow_recon_topography` (repoPath) — Detailed layer breakdown to align goal with architecture.
-    - `shadow_ops_chronicle` (limit: 10, repoPath) — More historical ADRs if 5 isn't enough.
-    - `shadow_ops_briefing` (scope: "project", altitude: "ground", repoPath) — Full detail with analytics, collisions, and working sets.
-3.  **Strategic Plan**: `shadow_ops_plan` (name, goal, outcomeContract, ...).
-    - **Strategy DAG**: Define logical steps and verification rules.
-    - **Initiative vs Mission**: Decide if this is a parent (Initiative) or a leaf (Mission). Parent missions auto-complete via cascade when all children finish.
-4.  **Alignment**: Present the plan to the user. Do not begin execution until the user approves the strategy.
+## Create the mission
 
-## Precise Tooling
+Use `shadow_ops_plan` with the fields that matter:
 
-| Setup Action          | Precise Tool Call                          | Usage                                                                                               |
-| :-------------------- | :----------------------------------------- | :-------------------------------------------------------------------------------------------------- |
-| **Session Start**     | `shadow_ops_context`                       | **START HERE** — hologram + chronicle + briefing in one call                                        |
-| **Establish Plan**    | `shadow_ops_plan`                          | Create the mission and strategy.                                                                    |
-| **Architectural Map** | `shadow_recon_topography`                  | Contextualize the target layers (if context wasn't enough).                                         |
-| **Detailed Briefing** | `shadow_ops_briefing` (altitude: "ground") | Full analytics, collisions, working sets.                                                           |
-| **Lean Briefing**     | `shadow_ops_briefing` (altitude: "orbit")  | Counts + candidates only (~200 tokens).                                                             |
-| **Graph View**        | `shadow_ops_graph`                         | Visualize the initiative's hierarchy.                                                               |
-| **Theme Patterns**    | `shadow_ops_crystallize_theme`             | Before planning: surface recurring themes across past missions to avoid repeating solved problems.  |
-| **Prior Handoffs**    | `shadow_ops_handoff_read`                  | In multi-agent contexts: retrieve typed findings from a prior RECON agent before defining strategy. |
-| **Event Mesh**        | `shadow_analyze_mesh`                      | When planning event-driven or API work: map all HTTP routes, socket events, pubsub topics.          |
+- `name`: short, concrete title
+- `goal`: what changes and why
+- `outcomeContract`: binary success test
+- `strategy`: JSON step graph when the work has multiple stages
+- `workingSet`: expected files or directories
+- `templateId`: `refactoring`, `feature`, or `bug-fix`
+- `parentId`: when this mission belongs under an initiative
 
-_Note: **Always start with `shadow_ops_context`** for instant mission landscape + architectural context. Ensure the `outcomeContract` is binary and verifiable. Parent initiatives auto-cascade on child completion — no manual closing needed._
+## Planning rules
 
-## Briefing Altitude Levels
-
-- **`orbit`** (~200 tokens): Counts + relevance-ranked candidates only. Use for quick checks.
-- **`atmosphere`** (default): Strategy graphs, crystal summaries, hierarchy, analytics.
-- **`ground`** (full): Raw logs, working sets, collision analysis, ancestor activity.
-
-## Intent Logging (Strategic Quality)
-
-Capture the "Why" and "How" during the planning phase to ensure the final ADR has architectural depth.
-
-- **Decision Logs**: Capture why a specific strategy or library was chosen.
-- **Discovery Logs**: Record insights found during initial reconnaissance.
-
-**Hand-off**: Once the mission is planned and logged, the setup phase is over. Execute via `/continue`.
+- Prefer a leaf mission when one deliverable can be completed in one run.
+- Use a parent initiative only when the work is intentionally split into child missions.
+- Keep `outcomeContract` verifiable. "Looks good" is not a contract.
+- If API or event boundaries matter, use `shadow_analyze_mesh({ repoPath, topic, type? })` with a concrete route or topic fragment.
+- Present the plan for approval before execution. Use `/continue` for the actual implementation pass.

package/skills/shadow_onboard/SKILL.md

@@ -1,39 +1,30 @@
 ---
 name: onboard
-description: Initialize and analyze a new repository for deep intelligence by building semantic index, syncing state, activating git hooks, and establishing missions. Use when onboarding to a new repository, initializing Shadow Engine, setting up git hooks, or when the user asks about repository setup, initialization, or first-time configuration.
+description: Initialize and analyze a repository for Shadow workflows. Use when onboarding a repo, bootstrapping indexes and hooks, checking intelligence health, or preparing the first mission.
 ---
 
-# Repository Onboarding
-
-Initialize and analyze a new repository for deep intelligence.
-
-## Workflow
-
-1.  **Semantic Init**: `shadow_recon_onboard` (repoPath) — **Only run once** per repo to build the baseline. Auto-populates the hologram.
-2.  **Read Hologram**: `shadow_recon_hologram` (repoPath) — Get instant architectural context (~1300 tokens: topography + gravity zones).
-3.  **Unified Sync**: `shadow_sync_trace` (repoPath) — **The One-Stop Shop**. Performs indexing + ghost analysis + mission re-hydration.
-4.  **Active Briefing**: `shadow_ops_briefing` (scope: "project", altitude: "atmosphere", repoPath) — Resumes the shared backlog with relevance-ranked candidates.
-    - Use `altitude: "orbit"` for a lean overview (~200 tokens), or `altitude: "ground"` for full detail.
-5.  **Architectural Deep Dive** (optional):
-    - `shadow_recon_topography` (repoPath) — View layers (Entry/Logic/Data/Utility/Test).
-    - `shadow_ops_chronicle` (limit: 5, repoPath) — Narrative feed.
-    - `shadow_analyze_mesh` (repoPath) — If repo is event-driven: map HTTP routes, socket events, pubsub topics immediately.
-    - `shadow_env_diagnose` (repoPath) — Verify environment health: hooks installed, index state, ember daemon status.
-6.  **Hooks Activation**: `shadow_env_hooks` (action: "install", repoPath) — installs post-commit and **post-checkout** hooks. Post-checkout fires incremental reindex in background on every branch switch.
-7.  **Establish Mission**: `shadow_ops_plan` (name, goal, repoPath).
-
-## Precise Tooling
-
-| Action            | Atomic Tool                                                                          |
-| :---------------- | :----------------------------------------------------------------------------------- |
-| **Index**         | `shadow_recon_onboard`                                                               |
-| **Hologram**      | `shadow_recon_hologram` (repoPath)                                                   |
-| **Layers**        | `shadow_recon_topography`                                                            |
-| **History**       | `shadow_ops_chronicle` (limit: 10)                                                   |
-| **Resume (lean)** | `shadow_ops_briefing` (scope: "project", altitude: "orbit")                          |
-| **Resume (full)** | `shadow_ops_briefing` (scope: "project", altitude: "atmosphere")                     |
-| **Hooks**         | `shadow_env_hooks` (action: "install")                                               |
-| **Env Health**    | `shadow_env_diagnose` (repoPath) — hooks status, index state, ember warming progress |
-| **Event Mesh**    | `shadow_analyze_mesh` (repoPath) — event-driven repos: routes + topics surface       |
-
-_Note: Always use absolute paths for `repoPath`. Call `shadow_recon_hologram` immediately after init for instant architectural context. `shadow_env_hooks` now installs both post-commit and post-checkout hooks — branch switches will auto-reindex in background via Ember daemon._
+# Onboard
+
+Use this skill when a repository needs its first Shadow pass or when a fresh clone needs to be made operational.
+
+## Core workflow
+
+1. `shadow_recon_onboard({ repoPath })`
+2. `shadow_recon_hologram({ repoPath, compact: true })`
+3. `shadow_sync_trace({ repoPath })`
+4. `shadow_ops_health({ repoPath })`
+5. `shadow_ops_context({ repoPath, compact: true })`
+
+## Useful follow-ups
+
+- `shadow_recon_topography({ repoPath })` for layer breakdown.
+- `shadow_ops_chronicle({ repoPath, limit: 5 })` for recent decisions.
+- `shadow_env_diagnose({ repoPath })` for hooks, index, and daemon health.
+- `shadow_env_hooks({ repoPath, action: "install", enableAutoRefresh: true, enableSymbolHealing: true })`
+- `shadow_ops_plan({ repoPath, name, goal, outcomeContract? })` for the first mission.
+
+## Rules
+
+- Always use an absolute `repoPath`.
+- `shadow_recon_onboard` is the baseline bootstrap; `shadow_sync_trace` is the normal follow-up maintenance pass.
+- Do not call `shadow_analyze_mesh` without a concrete `topic`.