@rkarim08/sia 1.0.0

package/skills/sia-execute-plan/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: sia-execute-plan
+description: Executes implementation plans with SIA's staleness detection, per-task convention checks, and session resumption. Use when following a written implementation plan, resuming plan execution, or running through task checklists.
+---
+
+## Invariants
+
+> These rules have NO exceptions. Executing a stale plan wastes more time than checking.
+>
+> 1. YOU MUST run the staleness check before executing any task. If a plan-referenced
+>    file has been modified after the plan was written, STOP and alert the developer.
+>    Do NOT proceed with a stale plan without explicit developer approval.
+> 2. YOU MUST query SIA for conventions before each task. "The plan already says how
+>    to do it" is not an excuse — conventions may have changed since the plan was written.
+> 3. YOU MUST NOT invoke sia-finish until ALL plan tasks are complete and verified.
+>    Partial completion is not completion.
+
+## Red Flags — If You Think Any of These, STOP
+
+| Thought | Why It's Wrong |
+|---------|---------------|
+| "The plan is recent, I can skip the staleness check" | Plans go stale faster than you expect. The check takes seconds; a stale-plan bug takes hours. |
+| "The plan already specifies conventions" | Conventions evolve. The graph is current; the plan may not be. |
+| "I'll finish the remaining tasks later" | sia-finish on a partial plan creates a misleading PR. Complete ALL tasks first. |
+| "This task is simple enough to skip the convention query" | Simple tasks done wrong compound into complex problems. Always query. |
+
+# SIA-Enhanced Plan Execution
+
+Execute plans with staleness detection, per-task convention injection, and session resumption from SIA's knowledge graph.
+
+## Checklist
+
+```
+- [ ] Step 0: YOU MUST run staleness check — sia_by_file for each plan-referenced file. If any file changed since plan creation, STOP and alert. No exceptions.
+- [ ] Step 1: Load and review plan, cross-reference against current graph state. Flag any contradictions.
+- [ ] Step 2: For EACH task, YOU MUST query SIA for area conventions before starting. A task executed without this query may violate project standards.
+- [ ] Step 3: Invoke sia-finish ONLY after ALL tasks are complete and verified. Partial completion is not completion.
+```
+
+## Workflow
+
+### Step 0 — Staleness Check (NEW)
+
+Before starting execution:
+
+```
+sia_search({ query: "<plan area>", limit: 10 })
+```
+
+For each file referenced in the plan, check if it was modified after the plan was written:
+
+```
+sia_by_file({ file_path: "<referenced_file>" })
+```
+
+If entities show recent modifications not accounted for in the plan, warn:
+
+> "The plan references `src/auth/login.ts` which was modified after the plan was written. The plan may need updating."
+
+### Step 1 — Load and Review Plan (enhanced)
+
+Standard: read the plan file, identify concerns.
+
+**Enhancement:** Cross-reference plan files against graph entities to identify any that have changed or have new conventions since the plan was written.
+
+### Step 2 — Execute Tasks (ENHANCED)
+
+For each task, before starting:
+
+```
+sia_search({ query: "conventions <task area>", node_types: ["Convention"], limit: 5 })
+sia_by_file({ file_path: "<task target file>" })
+```
+
+Include relevant conventions in the task context so the implementation follows project patterns.
+
+After each task, the session resume system (Phase J) captures progress automatically.
+
+### Step 3 — Complete Development (same as standard)
+
+Invoke sia-finish for branch completion.
+
+## Key Principle
+
+**Plans go stale. The graph knows what changed.** Always verify plan assumptions against current graph state before executing.

package/skills/sia-export-import/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sia-export-import
+description: Exports and imports SIA knowledge graphs as portable JSON for backup, migration, or sharing. Use when backing up the graph, migrating to a new machine, or sharing knowledge between projects.
+---
+
+# SIA Export & Import
+
+Export the knowledge graph to portable JSON or import from a previous export.
+
+## Export
+
+Serialize the active graph (entities, edges, communities, cross-repo edges) to JSON:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/export.ts --output graph-export.json
+```
+
+The export includes:
+- All active entities (not invalidated, not archived)
+- All active edges
+- All communities
+- Cross-repo edges (if in a workspace)
+
+## Import
+
+Load a previously exported graph:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/import.ts --input graph-export.json --mode merge
+```
+
+### Import Modes
+
+- **merge** (default): Runs imported entities through the consolidation pipeline — deduplicates against existing entities and only creates new edges when both endpoints exist
+- **replace**: Archives all existing active entities, then bulk-inserts everything from the export
+
+## When To Use
+
+- **Backup**: Export before major refactoring or destructive operations
+- **Migration**: Move knowledge between machines or environments
+- **Sharing**: Share project knowledge with team members who haven't run SIA
+- **Recovery**: Restore from a previous export if something goes wrong (also see `sia-rollback`)
+
+## Related
+
+- Use `rollback` to restore from automatic snapshots:
+  ```bash
+  bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/rollback.ts
+  ```

package/skills/sia-export-knowledge/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: sia-export-knowledge
+description: Exports the knowledge graph as a human-readable markdown document covering decisions, conventions, bugs, and architecture. Use for team onboarding, documentation generation, or sharing knowledge outside SIA.
+---
+
+# SIA Knowledge Export
+
+Generate a comprehensive markdown document summarizing everything SIA knows about your project.
+
+## Usage
+
+**Default** (writes to `KNOWLEDGE.md`):
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts export-knowledge
+```
+
+**Custom output path:**
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts export-knowledge --output docs/project-knowledge.md
+```
+
+**Custom project name:**
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts export-knowledge --name "My Project"
+```
+
+## What It Generates
+
+A structured markdown document with:
+
+1. **Architectural Decisions** — what was chosen, why, and what was rejected
+2. **Coding Conventions** — patterns and rules to follow
+3. **Known Issues** — active bugs with descriptions
+4. **Solutions** — how past bugs were fixed
+5. **Key Concepts** — domain terminology and system behavior
+6. **Architecture** — community structure showing module clusters
+
+Each entry includes: date captured, trust tier (verified/code-derived/inferred/external), and affected files.
+
+## When To Use
+
+- **Team onboarding** — share with new developers before their first session
+- **Knowledge audit** — review what SIA has captured, identify gaps
+- **External sharing** — generate a knowledge summary for stakeholders
+- **Backup** — human-readable export of the knowledge graph
+- **Documentation** — commit as living documentation alongside code

package/skills/sia-finish/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: sia-finish
+description: Finishes development branches using SIA — generates semantic PR summaries from the knowledge graph, captures branch decisions, and updates the graph post-merge. Use when implementation is complete, all tests pass, and the branch is ready for merge or PR.
+---
+
+## Invariants
+
+> These rules have NO exceptions. A PR without knowledge context is a missed opportunity.
+>
+> 1. YOU MUST query SIA for branch decisions before creating the PR. "I remember
+>    what I did" is not sufficient — the graph contains entities from sessions
+>    you may not recall.
+> 2. NEVER create a PR without a Knowledge Captured section. If the branch truly
+>    captured zero entities, state explicitly: "No decisions, conventions, or bugs
+>    were captured during this branch." An empty omission is not acceptable.
+> 3. YOU MUST call `sia_note` after merge to capture the branch summary.
+>    A merge without post-merge capture is incomplete.
+
+## Red Flags — If You Think Any of These, STOP
+
+| Thought | Why It's Wrong |
+|---------|---------------|
+| "This PR is too small for a knowledge section" | Small PRs with undocumented decisions are how institutional knowledge is lost. |
+| "The PR description already explains everything" | PR descriptions are not queryable by future sessions. The graph is. Capture anyway. |
+| "I'll add the knowledge section later" | You won't. Do it now. |
+| "Tests passed, so I can skip the SIA query" | Tests verify correctness, not knowledge. The SIA query surfaces decisions worth documenting. |
+| "No decisions were made on this branch" | Every branch makes decisions — even "keep the existing approach" is a decision worth noting. |
+
+# SIA-Enhanced Branch Finishing
+
+Finish a development branch with graph-powered semantic PR summaries and post-merge knowledge capture.
+
+## Checklist
+
+```
+- [ ] Step 0: YOU MUST query SIA for branch decisions/conventions/bugs before creating any PR. No exceptions.
+- [ ] Step 1: Hard gate — tests MUST pass. A PR with failing tests is not ready. Period.
+- [ ] Steps 2-3: Determine base branch, present options (merge/PR/cleanup)
+- [ ] Step 4: Create PR with Knowledge Summary section from graph entities. NEVER omit this section.
+- [ ] Post-merge: YOU MUST capture branch summary to graph via sia_note. A merge without this call is incomplete.
+```
+
+## Workflow
+
+### Step 0 — Branch Knowledge Summary (NEW)
+
+Before running tests or creating a PR:
+
+```
+sia_search({ query: "decisions conventions <branch work area>", limit: 20 })
+```
+
+Collect all entities captured during this branch's lifetime. These become the PR's semantic summary.
+
+### Step 1 — Verify Tests (same as standard)
+
+Hard gate — tests must pass.
+
+### Step 2-3 — Determine Base Branch + Present Options (same as standard)
+
+### Step 4, Option 2 — Create PR (ENHANCED)
+
+**For the full PR template:** See [pr-summary-template.md](pr-summary-template.md)
+
+When creating a PR, include a **Knowledge Summary** section built from graph entities:
+
+```markdown
+## Summary
+- [Standard git diff summary]
+
+## Knowledge Captured
+### Decisions Made
+- [Decision entities created during this branch]
+
+### Conventions Established
+- [Convention entities]
+
+### Bugs Found & Fixed
+- [Bug + Solution entity pairs]
+```
+
+This gives reviewers semantic context — not just what changed, but WHY.
+
+### Post-Merge — Knowledge Capture (NEW)
+
+After merge:
+
+```
+sia_note({ kind: "Decision", name: "Merged: <branch purpose>", content: "<summary of all work done on this branch>" })
+```
+
+If branch snapshots exist (Phase D.5), trigger cleanup:
+
+```
+sia_snapshot_prune({ branch_names: ["<merged_branch>"] })
+```
+
+## Key Principle
+
+**PR descriptions should tell the story, not just list the diff.** SIA knows the decisions, conventions, and bugs from this branch — use them.

package/skills/sia-finish/pr-summary-template.md

@@ -0,0 +1,54 @@
+# Semantic PR Summary Template
+
+Use this template when creating PRs via sia-finish. The "Knowledge Captured" section is built from SIA graph entities collected during the branch's lifetime.
+
+## Template
+
+```markdown
+## Summary
+<Standard git diff summary — what changed, why>
+
+## Knowledge Captured
+
+### Decisions Made
+<For each Decision entity captured during this branch:>
+- **{decision.name}** — {decision.content} (rationale: {why})
+
+### Conventions Established
+<For each Convention entity:>
+- **{convention.name}** — {convention.content}
+
+### Bugs Found & Fixed
+<For each Bug + Solution pair:>
+- **{bug.name}** → Fixed by: {solution.name}
+  - Root cause: {bug.content}
+  - Fix: {solution.content}
+
+### Architecture Changes
+<If any community structure or module boundaries changed:>
+- {description of structural change}
+```
+
+## How to Populate
+
+### Step 1 — Query branch entities
+
+```
+sia_search({ query: "decisions conventions <branch work area>", limit: 20 })
+```
+
+### Step 2 — Filter to branch lifetime
+
+Only include entities captured AFTER the branch was created. Check `t_valid_from` against the branch creation date (from `git log --oneline --reverse HEAD...main | head -1`).
+
+### Step 3 — Pair Bugs with Solutions
+
+For each Bug entity, check if a Solution entity references it (via `relates_to` or matching name). Present them as pairs.
+
+### Step 4 — Omit empty sections
+
+If no Conventions were established, omit that section. Don't include empty headers.
+
+## Why This Matters
+
+Standard PR descriptions list the diff — WHAT changed. Graph-powered summaries add WHY: the decisions that drove the changes, the bugs that motivated fixes, the conventions that were established. Reviewers get semantic context, not just code context.

package/skills/sia-freshness/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: sia-freshness
+description: Generates a freshness report for the SIA knowledge graph — identifies stale, rotten, and fresh entities. Use when checking knowledge quality, before pruning, or when results seem outdated.
+---
+
+# SIA Freshness
+
+Generate a report on the health and freshness of knowledge in the graph.
+
+## Steps
+
+Run the freshness report:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/freshness.ts
+```
+
+## Report Contents
+
+The report classifies entities into three tiers:
+
+- **Fresh** (confidence >= 0.7): Recently validated, high-confidence knowledge
+- **Stale** (0.3 <= confidence < 0.7): May need revalidation
+- **Rotten** (confidence < 0.3): Likely outdated, candidates for pruning
+
+Additional metrics:
+- **Pending revalidation**: Entities flagged for review
+- **Average confidence by tier**: How confident the graph is in each trust level
+- **Last deep validation**: When the graph was last fully validated
+- **Index coverage**: Percentage of entities with source file mappings
+- **Native module status**: Whether tree-sitter is using native, WASM, or TypeScript fallback
+
+## When To Use
+
+- As a regular health check (weekly recommended)
+- Before major refactoring to understand graph quality
+- When search results seem outdated
+- After `sia-prune` to confirm cleanup effectiveness

package/skills/sia-history/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: sia-history
+description: Explores how the knowledge graph evolved over time with temporal filtering. Use when reviewing recent decisions, tracking knowledge evolution, or investigating when something was captured.
+---
+
+# SIA History
+
+Interactive temporal exploration of the project's knowledge graph.
+
+## Usage
+
+**Last 7 days** (default):
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts history
+```
+
+**Since a specific date:**
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts history --since 2026-03-01
+```
+
+**Filter by type:**
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts history --types Decision,Convention
+```
+
+**Filter by file:**
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts history --file src/auth/login.ts
+```
+
+## When To Use
+
+- "What decisions were made this week?"
+- "Show me the bug history for this module"
+- "What changed in the graph since last release?"
+- "What conventions were established recently?"
+
+## Also Available
+
+- `sia_at_time` MCP tool — query the graph at a specific point in time
+- `/sia-compare` — compare graph state between two time points

package/skills/sia-impact/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sia-impact
+description: Analyzes the impact of a planned code change — maps dependencies, callers, importers, and downstream effects using the knowledge graph. Use before refactoring, renaming, or modifying shared code.
+---
+
+# SIA Impact Analysis
+
+Before making a structural change (rename, move, split, delete, signature change), analyze what will be affected.
+
+## How To Use
+
+Provide the entity or file you plan to change:
+
+- `/sia-impact src/auth/login.ts` — impact of changing this file
+- `/sia-impact processPayment` — impact of changing this function
+- `/sia-impact UserProfile type` — impact of changing this type
+
+## Analysis Steps
+
+The impact analysis chains these SIA tools:
+
+### 1. Find the entity
+```
+sia_search({ query: "$ARGUMENTS", node_types: ["CodeEntity", "CodeSymbol"] })
+sia_by_file({ file_path: "$ARGUMENTS" })
+```
+
+### 2. Map incoming dependencies
+```
+sia_backlinks({ node_id: "<entity_id>" })
+```
+This shows everything that imports, calls, or depends on the target.
+
+### 3. Trace the ripple effect
+```
+sia_expand({ entity_id: "<dependent_id>", depth: 2, edge_types: ["calls", "imports", "depends_on"] })
+```
+For each direct dependent, check what depends on THEM.
+
+### 4. AST-level verification
+```
+sia_ast_query({ file_path: "<affected_file>", query_type: "imports" })
+sia_ast_query({ file_path: "<affected_file>", query_type: "calls" })
+```
+Get precise import and call sites in affected files.
+
+### 5. Check conventions
+```
+sia_search({ query: "conventions <area>", node_types: ["Convention"] })
+```
+Are there conventions about how changes should be made in this area?
+
+## Output Format
+
+Present the impact as a structured report:
+
+| File | Dependency | Impact Type | Action Needed |
+|---|---|---|---|
+| path/file.ts | imports X | Direct | Update import |
+| path/other.ts | calls X | Direct | Update call site |
+| path/test.ts | tests X | Direct | Update test |
+| path/downstream.ts | uses Y which uses X | Indirect | Verify behavior |
+
+## When To Use
+
+- Before renaming a function, class, or type
+- Before moving files between directories
+- Before changing a function's signature
+- Before splitting or merging modules
+- Before removing exports or APIs

package/skills/sia-index/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: sia-index
+description: Indexes external content into SIA's knowledge graph — markdown, URLs, and documents with automatic chunking. Use when adding documentation, design docs, or external references to the graph.
+---
+
+# SIA Index
+
+Index external content into the knowledge graph for future retrieval.
+
+## When To Use
+
+Use this skill when you need to:
+- Index documentation, meeting notes, or design docs
+- Fetch and index content from a URL
+- Add external knowledge to the project graph
+
+## MCP Tools
+
+### sia_index — Index text content
+
+```
+sia_index({
+  content: "## Architecture Decision\n\nWe chose PostgreSQL over MongoDB because...",
+  source: "architecture-review-2026-03",
+  tags: ["decision", "database", "architecture"]
+})
+```
+
+Parameters:
+- **content** (required): Markdown or plain text to index
+- **source** (optional): Source identifier for provenance tracking
+- **tags** (optional): Tags for categorization
+
+### sia_fetch_and_index — Fetch a URL and index its content
+
+```
+sia_fetch_and_index({
+  url: "https://docs.example.com/api-reference",
+  intent: "Index API documentation for reference",
+  tags: ["api", "documentation"]
+})
+```
+
+Parameters:
+- **url** (required): URL to fetch (must be a valid URL)
+- **intent** (optional): Why this content is being indexed
+- **tags** (optional): Tags for categorization
+
+## Notes
+
+- Content is chunked using content-type-aware strategies (heading-based for markdown, line-based for plain text)
+- Entities and relationships are automatically extracted from chunks
+- SSRF protection is built in — private IPs and DNS rebinding are blocked
+- Requires the ONNX embedding model for vector indexing (run `sia-doctor` to check)

package/skills/sia-install/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: sia-install
+description: Initializes SIA persistent memory in the current project — creates databases, registers repo, and configures hooks. Use for first-time SIA setup in a new project or repository.
+---
+
+# SIA Install
+
+Initialize SIA's persistent graph memory for the current project.
+
+## What This Does
+
+1. Creates the SIA databases (graph.db, episodic.db) for this repository
+2. Registers the repo in the global meta.db registry
+3. Runs an initial AST index of the codebase using tree-sitter
+
+## Steps
+
+1. Run the SIA install command:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/install.ts
+```
+
+2. Verify the databases were created by checking `~/.sia/` (or `$CLAUDE_PLUGIN_DATA` in plugin mode)
+
+3. Run an initial reindex to populate the knowledge graph:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/reindex.ts
+```
+
+4. Confirm SIA is working by running a test search using the `sia_search` MCP tool with query "project overview".
+
+## Troubleshooting
+
+If installation fails:
+- Run `sia-doctor` to check system health
+- Ensure bun is installed (`bun --version`)
+- Check that the project is a git repository (`git rev-parse --git-dir`)

package/skills/sia-lead-compliance/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: sia-lead-compliance
+description: Audits convention compliance across the codebase — checks every known convention against current code and reports violations. Use for code quality audits, tech lead reviews, or enforcing team standards.
+---
+
+# SIA Convention Compliance Audit
+
+Full-codebase audit of convention compliance.
+
+## Usage
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts lead-report --type compliance
+```
+
+Shows: each convention with compliance %, specific violations with file paths, overall compliance score.

package/skills/sia-lead-drift-report/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: sia-lead-drift-report
+description: Generates an architecture drift report — compares current codebase against captured decisions and conventions. Use when reviewing architectural health, during retrospectives, or checking for design divergence.
+---
+
+# SIA Architecture Drift Report
+
+Detect where the codebase has diverged from captured architectural decisions.
+
+## Usage
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts lead-report --type drift
+```
+
+Shows: decisions not being followed, convention violations, stale architecture entities, community structure changes.

package/skills/sia-lead-knowledge-map/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: sia-lead-knowledge-map
+description: Generates a knowledge distribution map showing module coverage and gaps. Use for identifying bus-factor risks, planning knowledge sharing, or onboarding prioritization.
+---
+
+# SIA Knowledge Distribution Map
+
+Visualize how knowledge is distributed across the codebase and team.
+
+## Usage
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts lead-report --type knowledge-map
+```
+
+Shows: entities per module, contributors per module, bus-factor risks, coverage gaps.