@rkarim08/sia 1.0.0

package/skills/sia-debug-workflow/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: sia-debug-workflow
+description: Debugs systematically using SIA's temporal knowledge graph — traces root cause through time, surfaces known bugs, and finds past solutions. Use when encountering bugs, errors, test failures, or unexpected behavior.
+---
+
+## Invariants
+
+> These rules have No exceptions. A debug session that violates them is incomplete.
+>
+> 1. YOU MUST query `sia_search` for known bugs BEFORE investigating. "I already
+>    know the cause" is the #1 reason developers re-debug solved problems.
+> 2. YOU MUST capture both a Bug entity AND a Solution entity after fixing.
+>    A fix without graph capture is an incomplete session. STOP and capture
+>    before moving on.
+> 3. If a Bug+Solution pair already exists in the graph, STOP investigating
+>    and apply the known fix. Do not re-derive what's already known.
+
+## Red Flags — If You Think Any of These, STOP
+
+| Thought | Why It's Wrong |
+|---------|---------------|
+| "I already know the root cause" | You know A root cause. The graph may know THE root cause — and it may be different. Query first. |
+| "This is a quick fix, I don't need the temporal query" | Quick fixes that skip temporal investigation are how regressions get re-introduced. |
+| "The bug is obvious from the stack trace" | Stack traces show symptoms, not causes. The graph shows causal history. |
+| "I'll capture the bug after I fix it" | If you forget (and you will), the next developer re-debugs from scratch. Capture NOW. |
+| "This bug isn't important enough to record" | Every bug is important enough. Future-you will thank present-you. |
+
+# SIA-Enhanced Systematic Debugging
+
+Debug methodically with SIA's temporal knowledge graph — adds temporal investigation ("when did it break?"), known bug history, and cross-session memory to standard debugging.
+
+## Checklist
+
+```
+- [ ] Phase 1: YOU MUST query SIA for known bugs/solutions BEFORE investigating. If a match exists, apply it — do not re-derive. Run sia_at_time. Check affected files.
+- [ ] Phase 2: Expand dependency chain with sia_expand. Find working patterns in the same community. Do NOT skip this — the bug may originate upstream.
+- [ ] Phase 3: Form ONE hypothesis, test minimally, verify. Do not shotgun multiple changes.
+- [ ] Phase 4: Fix, then YOU MUST capture both Bug AND Solution to graph. A debug session without sia_note calls for both is INCOMPLETE.
+```
+
+## 4-Phase Workflow
+
+### Phase 1 — Root Cause Investigation (ENHANCED)
+
+**Standard steps:** Read errors, reproduce consistently, check recent changes.
+
+**SIA enhancement — add BEFORE standard investigation:**
+
+```
+sia_search({ query: "<error message or symptom>", task_type: "bug-fix", node_types: ["Bug", "Solution"], limit: 10 })
+```
+
+If a matching Bug+Solution pair exists → **stop investigating and apply the known fix.** Don't re-debug what's already been solved.
+
+If no match, use temporal investigation:
+
+```
+sia_at_time({ as_of: "<time_before_bug>", entity_types: ["Decision", "Bug", "Solution"] })
+```
+
+Compare the graph state before vs after the bug appeared. What decisions or changes coincide with the bug's introduction?
+
+For each affected file:
+
+```
+sia_by_file({ file_path: "<broken_file>" })
+```
+
+Check for known issues, recent changes, and related entities.
+
+**For detailed temporal investigation guidance:** See [temporal-investigation.md](temporal-investigation.md)
+
+### Phase 2 — Pattern Analysis (ENHANCED)
+
+**Standard steps:** Find working examples, compare, identify differences.
+
+**SIA enhancement:**
+
+```
+sia_expand({ entity_id: "<broken_entity>", depth: 2, edge_types: ["calls", "imports", "depends_on"] })
+```
+
+Map the full dependency chain. The bug may originate upstream — SIA's edges show what calls/imports the broken code.
+
+```
+sia_community({ entity_id: "<broken_entity>" })
+```
+
+Find structurally similar code in the same community that IS working. Compare the broken version against the working pattern.
+
+**For detailed causal chain analysis:** See [root-cause-tracing.md](root-cause-tracing.md)
+
+### Phase 3 — Hypothesis and Testing (same as standard)
+
+Form a single hypothesis, test minimally, verify. No SIA changes needed here — this phase is about focused experimentation.
+
+### Phase 4 — Implementation + Capture (ENHANCED)
+
+**Standard steps:** Create failing test, implement fix, verify.
+
+**SIA enhancement — after fixing:**
+
+```
+sia_note({ kind: "Bug", name: "<root_cause>", content: "<what was wrong, affected files, how it manifested>" })
+sia_note({ kind: "Solution", name: "<fix_description>", content: "<what was done, why it works>", relates_to: ["<bug_entity_id>"] })
+```
+
+**Always capture both the Bug and the Solution.** If 3+ fixes fail (standard threshold for questioning architecture), also query:
+
+```
+sia_search({ query: "<module> recurring bugs failures", node_types: ["Bug"], limit: 20 })
+```
+
+Check if this is a problem area with a history of bugs. If so, surface the pattern to the developer — this may need a design change, not another patch.
+
+**For test pollution bisection:** Run `skills/sia-debug-workflow/scripts/find-polluter.sh`
+
+## Key Principle
+
+**Time is your best debugging tool.** `sia_at_time` lets you ask "what was true before this broke?" — that's usually the fastest path to root cause.

package/skills/sia-debug-workflow/root-cause-tracing.md

@@ -0,0 +1,70 @@
+# Root Cause Tracing with SIA
+
+Trace bugs to their upstream origin by mapping dependency chains through the knowledge graph.
+
+## When to Use
+
+Use root cause tracing when:
+- The symptom is in file A but the cause is likely in a dependency
+- Multiple files are affected and you need to find the common ancestor
+- A fix in one place doesn't resolve the issue (upstream cause)
+
+## The Process
+
+### Step 1 — Map the broken entity's neighborhood
+
+```
+sia_expand({ entity_id: "<broken_entity>", depth: 2, edge_types: ["calls", "imports", "depends_on"] })
+```
+
+This returns a subgraph showing everything the broken code depends on and everything that depends on it.
+
+### Step 2 — Read the edges
+
+| Edge Type | Direction | Meaning |
+|---|---|---|
+| `calls` | outgoing | This code calls that code — bug may be in the callee |
+| `imports` | outgoing | This code imports that module — breaking change in dependency |
+| `depends_on` | outgoing | Logical dependency — behavioral contract may have changed |
+| `calls` | incoming | Something calls this code — caller may be passing bad input |
+
+### Step 3 — Follow the chain upstream
+
+For each dependency in the expansion:
+
+```
+sia_by_file({ file_path: "<dependency_file>" })
+```
+
+Check if the dependency has:
+- Recent Decision entities (was it intentionally changed?)
+- Bug entities (is it already known to be broken?)
+- Convention entities that were violated
+
+### Step 4 — Find the root
+
+The root cause is the **deepest entity in the chain where the bug originates**. Signs you've found it:
+- Changing this entity fixes all downstream symptoms
+- A Decision entity here explains why the behavior changed
+- A Convention entity here was violated
+
+### Step 5 — Verify with community context
+
+```
+sia_community({ entity_id: "<suspected_root>" })
+```
+
+Check if other entities in the same community are also affected. If yes, the root cause impacts the entire module — not just one file.
+
+## Worked Example
+
+**Symptom:** API endpoint returns 500.
+
+1. `sia_expand` on the endpoint handler → depends on `AuthMiddleware`, `UserService`, `Database`
+2. `sia_by_file` on each → `UserService` has a recent Decision: "Changed user lookup to use email instead of ID"
+3. The Decision coincides with the bug's timeline → root cause found
+4. Fix: Update the endpoint to pass email, not ID
+
+## Anti-Pattern: Fixing Symptoms
+
+**Never fix just the symptom.** If the API returns 500 because UserService changed its contract, adding a try-catch to the endpoint masks the real issue. Trace upstream, fix at the source.

package/skills/sia-debug-workflow/scripts/find-polluter.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Find which test pollutes another test by running bisection
+# Usage: find-polluter.sh <test-command> <failing-test> [test-dir]
+#
+# Example:
+#   find-polluter.sh "bun test" "src/auth/login.test.ts" "src/"
+#
+# Runs the failing test after each other test file individually
+# to find which one leaves behind state that causes the failure.
+
+set -euo pipefail
+
+TEST_CMD="${1:?Usage: find-polluter.sh <test-command> <failing-test> [test-dir]}"
+FAILING_TEST="${2:?Usage: find-polluter.sh <test-command> <failing-test> [test-dir]}"
+TEST_DIR="${3:-.}"
+
+# Discover all test files except the failing one
+mapfile -t TEST_FILES < <(find "$TEST_DIR" -name "*.test.*" -o -name "*.spec.*" | grep -v "$FAILING_TEST" | sort)
+
+echo "Searching ${#TEST_FILES[@]} test files for polluter of $FAILING_TEST"
+echo "---"
+
+# Verify the failing test actually fails in isolation first
+if $TEST_CMD "$FAILING_TEST" &>/dev/null; then
+  echo "The test passes when run alone — this IS a pollution issue."
+else
+  echo "The test fails even in isolation — not a pollution issue."
+  echo "Debug the test itself, not other tests."
+  exit 1
+fi
+
+# Bisection
+lo=0
+hi=$((${#TEST_FILES[@]} - 1))
+
+while [ $lo -le $hi ]; do
+  mid=$(( (lo + hi) / 2 ))
+  subset=("${TEST_FILES[@]:0:$((mid+1))}")
+
+  echo "Testing files 0..$mid (${#subset[@]} files)..."
+
+  # Run subset + failing test together
+  if $TEST_CMD "${subset[@]}" "$FAILING_TEST" &>/dev/null; then
+    echo "  Pass — polluter is in files $((mid+1))..$hi"
+    lo=$((mid + 1))
+  else
+    echo "  FAIL — polluter is in files $lo..$mid"
+    hi=$((mid - 1))
+  fi
+done
+
+if [ $lo -lt ${#TEST_FILES[@]} ]; then
+  echo "---"
+  echo "Found polluter: ${TEST_FILES[$lo]}"
+  echo ""
+  echo "Next steps:"
+  echo "  1. Run: $TEST_CMD ${TEST_FILES[$lo]} $FAILING_TEST"
+  echo "  2. Check what state ${TEST_FILES[$lo]} leaves behind"
+  echo "  3. Add proper cleanup/teardown to the polluting test"
+else
+  echo "---"
+  echo "Could not isolate a single polluter."
+  echo "The pollution may require multiple tests interacting."
+fi

package/skills/sia-debug-workflow/temporal-investigation.md

@@ -0,0 +1,72 @@
+# Temporal Investigation with sia_at_time
+
+SIA's temporal queries let you ask "what was true before this broke?" — the fastest path to root cause for regressions.
+
+## When to Use
+
+```dot
+digraph {
+    "Bug reported" -> "Known bug in graph?";
+    "Known bug in graph?" -> "Apply known fix" [label="yes"];
+    "Known bug in graph?" -> "When did it start?" [label="no"];
+    "When did it start?" -> "Known time" [label="user told you"];
+    "When did it start?" -> "Bisect with git" [label="unknown"];
+    "Known time" -> "sia_at_time query";
+    "Bisect with git" -> "sia_at_time query";
+    "sia_at_time query" -> "Compare before/after";
+    "Compare before/after" -> "Identify causal change";
+}
+```
+
+## Choosing the Right Timestamp
+
+| Scenario | Timestamp Strategy |
+|---|---|
+| "It broke last week" | Use `as_of` = last Monday midnight |
+| "It broke after deploy X" | Use `as_of` = deploy timestamp from git tag |
+| "It was working in v2.1" | Use `as_of` = v2.1 release date |
+| "Not sure when" | Use git bisect first, then `sia_at_time` on the identified commit date |
+
+## The Query Pattern
+
+**Step 1 — Snapshot before the bug:**
+
+```
+sia_at_time({ as_of: "<before_bug>", entity_types: ["Decision", "Convention", "Bug", "Solution"] })
+```
+
+**Step 2 — Compare with current state:**
+
+```
+sia_search({ query: "<affected area>", task_type: "bug-fix", limit: 20 })
+```
+
+**Step 3 — Identify the delta:**
+
+Look for:
+- **New Decision entities** that appeared after `as_of` — these are changes that coincide with the bug
+- **Invalidated entities** (`t_valid_until` set) — something was intentionally changed
+- **New Bug entities** in the same area — related issues that may share a root cause
+
+## Interpreting Results
+
+**Strong signal:** A Decision entity was created near the bug's introduction date that modified the affected module. This is likely causal.
+
+**Weak signal:** Only Convention changes in the timeframe. Conventions rarely cause bugs — look deeper.
+
+**No signal:** The graph has no entities near the timestamp. Fall back to git log analysis and `sia_by_file` for structural investigation.
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Querying too narrow a window | Widen by 2x — bugs often manifest days after the causal change |
+| Ignoring `t_valid_until` entities | These are CHANGES — exactly what you're looking for |
+| Trusting Tier 3 timestamps blindly | Tier 3 entities have `t_valid_from = null` sometimes — verify against git |
+| Skipping `sia_by_file` after temporal | Always check the affected file's current graph state too |
+
+## Red Flags
+
+- **3+ temporal queries with no signal** → The bug predates the graph. Switch to pure git investigation.
+- **Conflicting temporal data** → Check for `conflict_group_id` on results. Resolve conflicts before debugging.
+- **Bug reintroduced** → Same Bug entity appears, gets fixed (Solution), then reappears. This is a systemic issue — surface to developer.

package/skills/sia-digest/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: sia-digest
+description: Generates a daily knowledge digest summarizing recent decisions, bugs, conventions, and changes captured by SIA. Use at the start of a session, for daily standups, or when the user asks what changed recently.
+---
+
+# SIA Digest
+
+Generate a summary of recent knowledge captured in the graph.
+
+## Steps
+
+Run the digest command:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/digest.ts
+```
+
+This produces a markdown summary including:
+- Decisions made in the last 24 hours
+- New conventions established
+- Bugs discovered and solutions applied
+- Code areas with the most activity
+- Community-level changes

package/skills/sia-dispatch/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: sia-dispatch
+description: Dispatches parallel agents using SIA's community detection for independence verification and auto-extracted subgraph context per agent. Use when facing 2+ independent tasks, parallelizing work, or dispatching subagents.
+---
+
+# SIA-Enhanced Parallel Agent Dispatch
+
+Dispatch parallel agents with graph-powered independence verification and rich per-agent context extraction.
+
+## Checklist
+
+```
+- [ ] Step 1: Query sia_community, verify domains are in different communities
+- [ ] Step 2: For each agent — extract conventions, bugs, dependencies from graph
+- [ ] Step 3: Dispatch agents with graph context in task descriptions
+- [ ] Step 4: After integration — sia_expand to verify no cross-domain breakage
+```
+
+## Workflow
+
+### Step 1 — Identify Independent Domains (ENHANCED)
+
+Instead of guessing independence, query the graph:
+
+```
+sia_community({ level: 0 })
+```
+
+Community clusters represent modules that are tightly connected internally but loosely connected externally. Tasks within the SAME community should be sequential. Tasks in DIFFERENT communities can be parallel.
+
+For each proposed parallel task, verify independence:
+
+```
+sia_expand({ entity_id: "<domain_a_entity>", depth: 2, edge_types: ["calls", "imports", "depends_on"] })
+sia_expand({ entity_id: "<domain_b_entity>", depth: 2, edge_types: ["calls", "imports", "depends_on"] })
+```
+
+If the expansion graphs overlap (shared entities), the tasks are NOT independent. Warn and suggest sequential execution.
+
+### Step 2 — Create Agent Tasks (ENHANCED)
+
+**For task description format:** See [agent-task-template.md](agent-task-template.md)
+
+For each agent, auto-extract the relevant subgraph:
+
+```
+sia_by_file({ file_path: "<agent's primary file>" })
+sia_search({ query: "conventions <agent's domain>", node_types: ["Convention"], limit: 5 })
+sia_search({ query: "bugs <agent's domain>", node_types: ["Bug"], limit: 5 })
+```
+
+Include the results in each agent's task description:
+- Known conventions for this area
+- Known bugs to watch for
+- Dependency relationships to respect
+
+### Step 3-4 — Dispatch + Integrate (enhanced)
+
+Standard dispatch and review, but after integration:
+
+```
+sia_expand({ entity_id: "<modified_entity>", depth: 1 })
+```
+
+Verify that no agent's changes broke another's domain by checking edge integrity.
+
+## Key Principle
+
+**Community structure determines parallelizability.** Don't guess — let the graph's clustering tell you what's independent.

package/skills/sia-dispatch/agent-task-template.md

@@ -0,0 +1,99 @@
+# Agent Task Template
+
+Use this template when constructing task descriptions for parallel agents dispatched via sia-dispatch.
+
+## Template
+
+For each agent, construct the task description using this structure:
+
+```
+Agent tool:
+  description: "<3-5 word task summary>"
+  prompt: |
+    ## Task
+    <What this agent should accomplish>
+
+    ## Graph Context
+    ### Conventions for this area
+    <Paste sia_search Convention results here>
+
+    ### Known bugs to watch for
+    <Paste sia_search Bug results here>
+
+    ### Dependencies
+    <Paste sia_by_file results — what calls/imports/depends_on this code>
+
+    ## Constraints
+    - Do NOT modify files outside your domain: <list files>
+    - Follow these conventions: <list from graph>
+    - Test for these known edge cases: <list from Bug entities>
+
+    ## When You're Stuck
+    - If you need to modify a file outside your domain → STOP and report
+    - If a convention conflicts with the task → report the conflict
+    - If tests fail for reasons unrelated to your changes → report, don't fix
+```
+
+## How to Fill the Template
+
+### Step 1 — Extract conventions
+
+```
+sia_search({ query: "conventions <agent's domain>", node_types: ["Convention"], limit: 5 })
+```
+
+Include each Convention's `name` and `content` in the "Conventions" section.
+
+### Step 2 — Extract known bugs
+
+```
+sia_search({ query: "bugs <agent's domain>", node_types: ["Bug"], limit: 5 })
+```
+
+Include each Bug's `name` as an edge case to test for.
+
+### Step 3 — Extract dependencies
+
+```
+sia_by_file({ file_path: "<agent's primary file>" })
+```
+
+List incoming edges (callers) as things the agent must not break.
+
+## Worked Example
+
+```
+Agent tool:
+  description: "Implement auth middleware"
+  prompt: |
+    ## Task
+    Implement JWT validation middleware for the Express API.
+
+    ## Graph Context
+    ### Conventions for this area
+    - [Convention: Middleware returns structured JSON errors] — all middleware
+      must return { error: string, code: number }, not plain text
+    - [Convention: Auth tokens in Authorization header] — Bearer scheme only
+
+    ### Known bugs to watch for
+    - [Bug: Token expiry off-by-one] — JWT expiry check was < instead of <=,
+      caused 401s at exact expiry second. Test boundary condition.
+
+    ### Dependencies
+    - `src/routes/users.ts` imports this middleware
+    - `src/routes/admin.ts` imports this middleware
+    - Changes must be backward-compatible with both consumers
+
+    ## Constraints
+    - Do NOT modify files outside src/middleware/
+    - Follow structured JSON error convention
+    - Test token expiry boundary condition
+
+    ## When You're Stuck
+    - If you need to modify route files → STOP and report
+    - If the JWT library API doesn't match expectations → report
+```
+
+## Why This Matters
+
+Without structured context, parallel agents make incompatible assumptions. This template ensures each agent gets the same quality of graph context, preventing post-integration conflicts.

package/skills/sia-doctor/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: sia-doctor
+description: Runs SIA system health diagnostics — checks databases, providers, tree-sitter, embeddings, and connectivity. Use when SIA tools return errors, knowledge seems missing, or the user reports SIA issues.
+---
+
+# SIA Doctor
+
+Run comprehensive diagnostics on the SIA installation.
+
+## Steps
+
+Run the doctor command:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/doctor.ts
+```
+
+This checks:
+- Database integrity (graph.db, episodic.db, meta.db, bridge.db)
+- Tree-sitter parser availability and grammar loading
+- ONNX embedding model availability
+- LLM provider connectivity (if configured)
+- Hook registration status
+- Disk usage
+
+## MCP Tool
+
+You can also run diagnostics via the `sia_doctor` MCP tool with targeted checks:
+
+```
+sia_doctor({ checks: ["all"] })
+sia_doctor({ checks: ["graph_integrity", "onnx"] })
+```
+
+Valid check names: `runtimes`, `hooks`, `fts5`, `vss`, `onnx`, `graph_integrity`, `all`
+
+## Interpreting Results
+
+Each check reports: OK, Warning, or Error with remediation steps.

package/skills/sia-execute/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sia-execute
+description: Executes code in SIA's isolated sandbox environment with automatic knowledge capture. Use when running code snippets, testing expressions, or executing scripts with SIA context.
+---
+
+# SIA Execute
+
+Run code in an isolated sandbox with automatic knowledge graph integration.
+
+## When To Use
+
+Use this skill when you need to:
+- Execute code snippets in a sandboxed environment
+- Run an existing file in a sandbox subprocess
+- Batch multiple operations (execute + search) in one call
+
+## MCP Tools
+
+### sia_execute — Run inline code
+
+```
+sia_execute({
+  code: "console.log('hello')",
+  language: "javascript",
+  intent: "Test logging output",
+  timeout: 10000
+})
+```
+
+Parameters:
+- **code** (required): The code to execute
+- **language** (optional): Runtime language (supports 14+ runtimes)
+- **intent** (optional): Description of what the code should do
+- **timeout** (optional): Execution timeout in ms (default: 30s, configurable via `sandboxTimeoutMs`)
+- **env** (optional): Environment variables to pass
+
+### sia_execute_file — Run an existing file
+
+```
+sia_execute_file({
+  file_path: "scripts/migrate.ts",
+  language: "typescript",
+  intent: "Run database migration"
+})
+```
+
+Parameters:
+- **file_path** (required): Path to the file to execute
+- **language** (optional): Override language detection
+- **command** (optional): Custom command to run the file
+- **intent** (optional): Description of expected behavior
+- **timeout** (optional): Execution timeout in ms
+
+### sia_batch_execute — Multiple operations in one call
+
+```
+sia_batch_execute({
+  operations: [
+    { type: "execute", code: "1 + 1", language: "python" },
+    { type: "search", query: "related algorithms" }
+  ],
+  timeout_per_op: 5000
+})
+```
+
+## Notes
+
+- Sandbox execution uses credential passthrough with an environment allowlist
+- Results are automatically indexed in the knowledge graph
+- Context mode activates when output exceeds the threshold, chunking results for better retrieval