@rkarim08/sia 1.0.0

package/skills/sia-learn/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: sia-learn
+description: Builds or refreshes SIA's complete knowledge graph — indexes code with tree-sitter, ingests docs, and detects communities. Use after major codebase changes, initial setup, or when the graph needs a full refresh.
+---
+
+# SIA Learn
+
+Build the complete knowledge graph for the current repository in one step.
+
+## What This Does
+
+1. **Install** (if needed) — creates SIA databases, registers the repo
+2. **Index code** — tree-sitter parse of all source files (25+ languages), extracts symbols, imports, calls
+3. **Ingest docs** — discovers and parses README.md, CLAUDE.md, ARCHITECTURE.md, ADRs, API docs, changelogs
+4. **Detect communities** — clusters related code into communities, generates summaries
+5. **Report** — prints what was learned
+
+## Usage
+
+**Full build** (first time or rebuild):
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts learn
+```
+
+**Incremental update** (fast — only changed files):
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts learn --incremental
+```
+
+**Force rebuild** (ignore caches and snapshots):
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts learn --force
+```
+
+**Quiet mode** (summary only):
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts learn --quiet
+```
+
+## Crash Recovery
+
+If the process crashes mid-run (OOM, Ctrl+C, power loss), re-running `/sia-learn` automatically resumes from the last checkpoint. A `.sia-learn-progress.json` file tracks progress and is deleted on successful completion.
+
+## When To Use
+
+- First time setting up SIA on a project
+- After pulling major changes from remote
+- When the knowledge graph feels stale or incomplete
+- After a large refactoring
+- When onboarding to a new codebase
+
+## After Learning
+
+Use SIA's MCP tools to query the knowledge graph:
+- `sia_search` — semantic search across all knowledge
+- `sia_community` — browse community-level summaries
+- `sia_by_file` — look up knowledge for specific files
+- `sia_expand` — explore entity neighborhoods

package/skills/sia-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: sia-plan
+description: Writes implementation plans using SIA's knowledge of module topology, architectural constraints, and project conventions. Use when creating multi-step implementation plans or breaking down specs into tasks.
+---
+
+# SIA-Enhanced Plan Writing
+
+Write implementation plans pre-loaded with architectural constraints, module boundaries, and conventions from SIA's knowledge graph.
+
+## Checklist
+
+```
+- [ ] Step 0: Load graph context — community structure, decisions, conventions
+- [ ] Step 1: Scope check — use community boundaries to find natural split points
+- [ ] Step 2: File structure — sia_by_file for each file to understand dependencies
+- [ ] Step 3: Task definition — embed graph context (conventions, dependencies, known bugs) per task
+- [ ] Step 4-6: Standard plan writing, review, handoff
+```
+
+## Workflow
+
+### Step 0 — Load Graph Context (NEW)
+
+Before file structure mapping, query the graph:
+
+```
+sia_community({ level: 1 })
+sia_search({ query: "<feature area> architecture patterns", node_types: ["Decision", "Convention"], limit: 15 })
+sia_search({ query: "file structure module organization <area>", node_types: ["Convention"], limit: 10 })
+```
+
+Use community structure to understand module boundaries. Use conventions to know how this codebase organizes code.
+
+### Step 1 — Scope Check (enhanced)
+
+When checking if the spec should be decomposed, use community boundaries from the graph to determine natural split points — not just intuition.
+
+### Step 2 — File Structure (ENHANCED)
+
+When mapping which files to create/modify:
+
+```
+sia_by_file({ file_path: "<each_file_to_modify>" })
+```
+
+For each file, understand:
+- What entities already exist in this file
+- What depends on this file (via edges)
+- What conventions apply to this area
+
+This prevents plans that unknowingly violate module boundaries or break downstream consumers.
+
+### Step 3 — Task Definition (ENHANCED)
+
+For each task, include relevant graph context in the task description:
+- "This file follows the [Convention Name] pattern — see entity [id]"
+- "Function X is called by Y and Z — changes must be backward-compatible"
+- "This area had a bug [Bug Name] — test for regression"
+
+### Step 4-6 — Standard plan writing, review, handoff
+
+**After writing the plan:** Dispatch plan reviewer subagent — see [plan-reviewer-prompt.md](plan-reviewer-prompt.md)
+
+Follow the standard plan document format, review loop, and execution handoff.
+
+## Key Principle
+
+**Plans that respect existing architecture succeed faster.** SIA's graph knows the module topology, conventions, and dependencies. Use this to write plans that work WITH the codebase, not against it.

package/skills/sia-plan/plan-reviewer-prompt.md

@@ -0,0 +1,63 @@
+# Plan Document Reviewer Prompt
+
+Use this template when dispatching a plan reviewer subagent after writing an implementation plan.
+
+**Purpose:** Verify the plan respects module boundaries, references correct conventions, doesn't contradict established decisions, and accounts for known dependencies.
+
+**Dispatch after:** Plan document is written.
+
+```
+Agent tool (general-purpose):
+  description: "Review plan against graph"
+  prompt: |
+    You are a plan reviewer with access to SIA's knowledge graph. Verify this plan
+    is sound and respects the project's architecture.
+
+    **Plan to review:** [PLAN_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Module boundaries | Does the plan modify files across community boundaries without acknowledging it? |
+    | Convention compliance | Does each task follow known conventions for its area? |
+    | Decision conflicts | Does any task contradict an established Decision entity? |
+    | Dependency awareness | Are downstream consumers of modified files accounted for? |
+    | Known bugs | Does the plan touch areas with known Bug entities without testing for regression? |
+    | Staleness | Were any referenced files modified after the plan was written? |
+
+    ## Verification Process
+
+    For each task in the plan:
+    1. Run `sia_by_file` on the target file
+    2. Check for Convention entities that apply
+    3. Check for Bug entities in the area
+    4. Verify no Decision entities conflict with the proposed changes
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation.**
+    A plan that doesn't mention every convention is fine — only flag conventions
+    that would be VIOLATED by the planned changes. Missing test coverage for a
+    known bug area IS worth flagging.
+
+    Approve unless there are structural problems that would lead to broken code
+    or architectural violations.
+
+    ## Output Format
+
+    ## Plan Review
+
+    **Status:** Approved | Issues Found
+
+    **Graph Conflicts (if any):**
+    - [Task N]: Conflicts with [Decision/Convention: name] — [why it matters]
+
+    **Dependency Risks:**
+    - [File X] is consumed by [Y, Z] — changes need backward compatibility
+
+    **Recommendations (advisory):**
+    - [suggestions for improvement]
+```
+
+**Reviewer returns:** Status, Graph Conflicts, Dependency Risks, Recommendations

package/skills/sia-playbooks/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: sia-playbooks
+description: Loads SIA task-specific playbooks for regression analysis, feature development, code review, or orientation. Called automatically by CLAUDE.md behavioral directives after task classification.
+---
+
+# SIA Task Playbooks
+
+This skill provides detailed step-by-step guidance for using SIA's knowledge graph during specific task types. The CLAUDE.md behavioral spec directs you here after task classification.
+
+## Available Playbooks
+
+Load the playbook matching your task type by reading the corresponding reference file in this skill's directory:
+
+| Task Type | Reference File |
+|---|---|
+| Bug fix / Regression | `reference-regression.md` |
+| Feature development | `reference-feature.md` |
+| Code review | `reference-review.md` |
+| Orientation / Architecture | `reference-orientation.md` |
+| Full tool reference | `reference-tools.md` |
+| Flagging guidance | `reference-flagging.md` |
+
+## Workflow
+
+1. CLAUDE.md classifies the task (bug-fix, feature, review, orientation)
+2. CLAUDE.md directs you to invoke `/sia-playbooks`
+3. Read the matching reference file from this skill's directory
+4. Follow the step-by-step guidance in the playbook
+5. The playbook tells you exactly which SIA tools to call and in what order

package/skills/sia-playbooks/reference-feature.md

@@ -0,0 +1,100 @@
+# Sia — Feature Implementation Playbook
+
+*Loaded by the base CLAUDE.md when `task_type = 'feature'`.*
+*Follow these steps in order. They replace the condensed Step 1 in the base module.*
+
+---
+
+## Feature Implementation
+
+Feature work benefits from Sia in two ways: understanding the architectural context
+before writing code (avoiding decisions that conflict with past choices), and discovering
+conventions that constrain implementation (patterns the team has established that must
+be followed). Both types of retrieval happen before a single line of code is written.
+
+**Step 1 — Structural orientation**
+
+```
+sia_community(feature_domain, level=1)
+```
+
+Get module-level structural orientation before touching any files. This tells you which
+existing modules are involved, how they relate, and what architectural patterns govern
+this area. For cross-cutting features that span multiple modules, call `sia_community`
+at level=2 first for a system-wide view, then level=1 for the relevant subsystem.
+
+**Step 2 — Decision and convention retrieval**
+
+```
+sia_search(feature_topic,
+  task_type='feature',
+  node_types=['Decision', 'Convention'],
+  limit=10)
+```
+
+This surfaces: architectural decisions that constrain how the feature must be built,
+conventions the implementation must follow, and prior work in this area that you should
+be consistent with. Pay particular attention to Convention entities — see Step 5.
+
+**Step 3 — File-scoped retrieval**
+
+```
+sia_by_file(file_path)   // for each file to be created or modified
+```
+
+For files in a linked repository within the workspace, use
+`sia_by_file(file_path, workspace=true)` — this surfaces cross-repo edges for that
+specific file. Call `sia_by_file` before `sia_search` when the file is the primary
+anchor; call after when the topic is the primary anchor.
+
+**Step 4 — Optional relationship traversal**
+
+If a returned Decision entity references related entities you need to understand before
+implementing, call:
+
+```
+sia_expand(entity_id, depth=1)
+```
+
+Use only when the relationship is directly decision-relevant, not out of curiosity. This
+consumes one of the two allowed `sia_expand` calls for the session.
+
+**Step 5 — Convention scanning (critical)**
+
+Before writing any code, scan all returned Convention entities carefully. Conventions
+are hard constraints, not style suggestions. If a Convention says "all errors must extend
+`AppBaseError`," that is a requirement, not a preference. Violations are bugs.
+
+State the applicable conventions before you start implementing:
+"Convention #conv-44 requires all DB access to go through the Repository layer — I'll
+route this through `UserRepository` rather than querying directly."
+
+**Step 6 — Cross-repo workspace search (if applicable)**
+
+If the feature spans linked repositories, also call:
+
+```
+sia_search(api_topic, workspace=true)
+```
+
+This surfaces API contracts, shared types, and cross-service calls that the feature
+must conform to. Only use `workspace: true` when the task genuinely crosses repo
+boundaries — it adds 400ms latency and cross-repo noise for single-repo tasks.
+
+**Step 7 — Implement**
+
+Implement following all retrieved conventions and prior decisions. Cite the relevant
+entities in comments where the constraint is non-obvious.
+
+**Step 8 — Flag if applicable**
+
+If flagging is enabled (`enableFlagging: true`) and you made an architectural decision
+during implementation: `sia_flag(decision_summary)`. If flagging is disabled, skip
+this step — the session-end capture will record the decision automatically, though
+with lower precision.
+
+---
+
+## Tool Budget for This Playbook
+
+This playbook uses 3 tool calls in the standard case: `sia_community` (1) + `sia_search` (2) + `sia_by_file` (3). The optional Step 4 `sia_expand` call pushes the count to 4, which exceeds the base module's 3-tool limit. This is permitted only when genuinely necessary — it consumes one of the two allowed `sia_expand` calls for the session. It does NOT consume a regression-exception slot. The 4-call regression exception applies exclusively to `task_type='bug-fix'` sessions. For straightforward features where `sia_expand` is not needed, stay within 3 calls.

package/skills/sia-playbooks/reference-flagging.md

@@ -0,0 +1,50 @@
+# Sia — Flagging Guidance
+
+*Loaded when flagging is enabled (`enableFlagging: true`) and you reach Step 4.*
+*`sia_flag` is only available when `sia enable-flagging` has been run.*
+
+---
+
+## When to Call `sia_flag`
+
+Call `sia_flag` at most 2–3 times per session, and only for:
+
+1. **An architectural decision made this session** that will constrain future work —
+   for example, choosing a pattern, library, or structural approach that other modules
+   should follow.
+2. **A non-obvious root cause** discovered during debugging — something that was not
+   evident from the code and that a future developer would need to know.
+3. **An explicit developer preference** stated during the session ("we always do X this
+   way," "never use Y for this").
+4. **A new cross-cutting pattern introduced** that other modules should replicate.
+
+The test: would the next developer who picks up this task need to know this? If yes,
+flag it. If they could infer it from the code in 30 seconds, do not flag it.
+
+---
+
+## When NOT to Call `sia_flag`
+
+- Routine code changes or normal implementation steps.
+- Things that are obvious from the code itself.
+- Single-line edits or minor refactors.
+- General best practices (Sia already knows these from the codebase).
+- Anything you would not bother to explain in a code review comment.
+
+The 2–3 per session maximum is a hard ceiling. Flagging everything degrades the
+signal-to-noise ratio in the graph. Be selective.
+
+---
+
+## How to Write a Good `reason`
+
+The reason should be a complete, self-contained description of what happened and why
+it matters. It will be stored and retrieved without context, so it must stand alone.
+
+Good: `"chose express-rate-limit at route level, not middleware — rate limits are per-endpoint not global"`
+Good: `"root cause: EventEmitter.on() not awaited in init.ts, fires before DB ready"`
+Bad: `"fixed the bug"` (not self-contained)
+Bad: `"important decision"` (no content)
+
+Keep it under 100 characters after sanitization. Colons, backticks, underscores, and
+forward slashes are all permitted in the reason string.

package/skills/sia-playbooks/reference-orientation.md

@@ -0,0 +1,92 @@
+# Sia — New Developer Orientation Playbook
+
+*Loaded by the base CLAUDE.md for architecture questions and new-developer orientation.*
+*Follow these steps in order. They replace the condensed Step 1 in the base module.*
+
+---
+
+## New Developer Codebase Orientation
+
+When a developer asks "how does this system work," "explain the architecture," or is
+orienting to an unfamiliar codebase, the goal is a coherent narrative — not a list of
+entity names. Sia's community detection has clustered the codebase into meaningful
+modules with generated summaries; use those summaries to build understanding rather than
+surfacing raw entity lists from `sia_search`.
+
+**Step 0 — Graph readiness check**
+
+Before calling `sia_community`, check whether the graph is large enough to have
+community structure. If `sia_community` returns `global_unavailable: true` (graph
+below 100 entities), skip Steps 1 and 2 entirely and go directly to Step 3. Tell
+the developer: "The memory graph is still building — Sia improves with each session.
+Here is what I can tell you from existing captured context:" then present the
+Step 3 `sia_search` results as a narrative (Step 4 still applies — no raw entity
+lists even in fallback mode).
+
+If `sia_community` returns zero communities (graph is large enough but the topic
+query matched nothing), do not stop. Continue to Step 3 (`sia_search`) and present
+whatever decisions and concepts are available.
+
+**Step 1 — System-wide structural view**
+
+```
+sia_community(query="architecture overview", level=2)
+```
+
+Level 2 gives a coarse architectural view: major subsystems, how they relate, and what
+the overall design intent is. This is the starting point for any orientation.
+
+**Step 2 — Subsystem drill-down**
+
+```
+sia_community(query=<developer's primary area>, level=1)
+```
+
+Level 1 gives module-level summaries. If the developer is focused on a specific area
+(authentication, data pipeline, API layer), drill into the relevant subsystem here.
+
+**Step 3 — Key decisions**
+
+```
+sia_search("architectural decisions constraints rationale",
+  node_types=['Decision'],
+  limit=10)
+```
+
+This surfaces the decisions that constrain future work — why certain patterns exist,
+what was tried and rejected, and what the team has committed to. This is the context
+that is hardest to recover from code alone.
+
+**Step 4 — Present as a narrative**
+
+Do not return a list of entity names. Synthesise the retrieved summaries and decisions
+into a coherent explanation of the system: how the major modules relate, what the key
+architectural decisions are, and what a developer needs to know before making changes.
+
+A good orientation response answers: what does this system do, how is it structured,
+what are the non-obvious constraints, and where should I start?
+
+---
+
+## Level Guide for `sia_community`
+
+`level=2` — Coarse architectural overview. Appropriate for system-wide questions,
+"explain the whole system," and first-day orientation.
+
+`level=1` — Subsystem / module level. Appropriate for "explain the auth module" or
+"how does the data pipeline work."
+
+`level=0` — Fine-grained cluster view. Rarely needed by the agent; more useful from
+the CLI when investigating a specific component. Do not use for orientation.
+
+Never call `sia_community` as a fallback for a failed `sia_search` — they serve
+different purposes. `sia_search` finds specific entities; `sia_community` explains
+structure.
+
+---
+
+## Tool Budget for This Playbook
+
+This playbook uses 3 tool calls: `sia_community(level=2)` (1) + `sia_community(level=1)`
+(2) + `sia_search` (3). This is exactly the 3-tool limit. No `sia_expand` is needed for
+orientation — community summaries already contain synthesised relationship context.

package/skills/sia-playbooks/reference-regression.md

@@ -0,0 +1,115 @@
+# Sia — Regression Investigation Playbook
+
+*Loaded by the base CLAUDE.md when `task_type = 'bug-fix'` (regression signal detected).*
+*Follow these steps in order. They replace the condensed Step 1 in the base module.*
+
+---
+
+## Regression Investigation
+
+A regression is any situation where something worked before and is now broken. The key
+capability that distinguishes Sia's regression support from generic memory retrieval is
+`sia_at_time`: it lets you query the graph as it existed at a point in the past, surfacing
+exactly what facts changed between then and now.
+
+**Step 1 — Initial search (current state)**
+
+```
+sia_search(symptom_description,
+  task_type='bug-fix',
+  node_types=['Bug', 'Solution', 'Decision'],
+  limit=10)
+```
+
+Scan results for entities matching the symptom, affected files, or known related
+components. Look for a prior instance of this bug, a Decision that was recently changed,
+or a Solution that should have prevented this.
+
+**Step 2 — Causal chain traversal (conditional)**
+
+If a relevant entity is found in Step 1, call:
+
+```
+sia_expand(entity_id, depth=1, edge_types=['supersedes', 'caused_by', 'solves'])
+```
+
+This surfaces what superseded the old fact, what caused the bug, and what solutions were
+previously applied. This call is optional — use it only when the Step 1 result points to
+a likely causal chain. It counts against the 2-call sia_expand session budget.
+
+**Step 3 — Temporal investigation (MANDATORY — never skip)**
+
+```
+// Initial call — use the default limit
+sia_at_time(
+  as_of='<estimated date regression began>',
+  tags=[<relevant tags>],
+  limit=20
+)
+```
+
+Important: `limit` applies to **both** `entities[]` and `invalidated_entities[]` simultaneously. Bumping `limit` to 50 on a re-call returns 50 current entities alongside 50 invalidated entities — the extra current entities are usually irrelevant to regression work and add response payload that may hit the `maxResponseTokens` cap. Prefer narrowed re-calls over blindly increasing `limit`.
+
+If the initial call returns `invalidated_count > invalidated_entities.length` (result is truncated), make a **narrowed follow-up** targeting causally relevant entity types rather than raising `limit` alone:
+
+```
+// Truncation follow-up — narrow by type to reduce current-entity noise
+sia_at_time(
+  as_of='<same date>',
+  entity_types=['Decision', 'Solution', 'Bug'],  // causally relevant types
+  tags=[<relevant tags>],
+  limit=50
+)
+```
+
+Without this call, the temporal investigation capability is completely unused. `sia_at_time`
+returns two arrays — read them in this order:
+
+`invalidated_entities[]` is the primary diagnostic signal. These are facts that ENDED on
+or before `as_of`. Each entry's `t_valid_until` is exactly when that fact stopped being
+true. **Entries with `t_valid_until` closest to `as_of` are the most temporally
+relevant** — they represent what changed most recently before the regression and are
+therefore the highest-priority root cause candidates. The array is sorted by
+`t_valid_until DESC` so the most relevant entries appear first.
+
+`entities[]` contains facts still valid at `as_of`. Compare these against the current
+`sia_search` output to see what has changed since that date.
+
+If `invalidated_count > invalidated_entities.length`, the result is truncated. Make
+additional narrowed calls using `entity_types` or `tags` to retrieve the remaining
+entries. Do not treat a truncated result as the complete picture.
+
+**Step 4 — Explain the delta**
+
+Present the findings to the developer with specific entity citations. The answer to
+"what caused the regression" should be grounded in one or more specific invalidated
+entities, not general speculation.
+
+**Step 5 — Flag if applicable**
+
+If flagging is enabled (`enableFlagging: true`) and the root cause is non-obvious:
+`sia_flag("Root cause: [description]")`. If flagging is disabled, skip this step.
+
+---
+
+## Edge Types for Regression Investigation
+
+When calling `sia_expand` during regression work, these edge types are most diagnostic:
+
+`supersedes` — what replaced the old Decision or Solution
+`caused_by` — what entity directly caused this Bug
+`solves` — what Solution was supposed to address this Bug
+`invalidates` — what action marked the old fact as no longer true
+
+Use `edge_types=['supersedes','caused_by','solves']` as the default filter for regression
+traversal. This keeps the neighborhood focused on causal relationships rather than
+structural dependencies, which tend to be less diagnostic for regression work.
+
+---
+
+## Tool Budget for This Playbook
+
+This playbook uses up to 4 tool calls, which is the permitted exception to the 3-tool
+invariant. The sequence is: `sia_search` (1) + conditional `sia_expand` (2) +
+`sia_at_time` (3) + one additional narrowed `sia_at_time` if truncated (4). If no
+causal entity is found in Step 1, skip `sia_expand` and stay within 3 calls.

package/skills/sia-playbooks/reference-review.md

@@ -0,0 +1,64 @@
+# Sia — PR / Code Review Playbook
+
+*Loaded by the base CLAUDE.md when `task_type = 'review'`.*
+*Follow these steps in order. They replace the condensed Step 1 in the base module.*
+
+---
+
+## PR / Code Review
+
+Code review with Sia is convention-first: retrieve the full set of project-specific
+conventions before looking at a single line of code. Generic best-practice rules are
+secondary. What matters is whether the change conforms to the patterns this team has
+established in this project.
+
+**Step 1 — Convention retrieval**
+
+```
+sia_search("conventions standards style patterns",
+  task_type='review',
+  node_types=['Convention'],
+  limit=15)
+```
+
+Use `limit=15` here — this is one of the few contexts where maximum coverage matters
+more than latency. You need the full convention set before evaluating the code.
+
+**Step 2 — File-scoped retrieval**
+
+For each file in the PR:
+
+```
+sia_by_file(file_path)
+```
+
+This surfaces decisions, patterns, and prior bug history for each changed file. A file
+that has had recurring bugs around a specific pattern is worth scrutinising more closely.
+
+**Step 3 — Evaluate each change**
+
+Compare each change against the retrieved conventions and file-specific context. The
+evaluation question is: does this change conform to the conventions the team has
+established, and does it respect the decisions that constrain this file?
+
+**Step 4 — Report violations by entity ID**
+
+For each violation, cite the specific Convention entity that is breached. Do not
+paraphrase the convention — reference it by ID so the developer can look it up:
+
+> "Violation of Convention #conv-44: direct database query in service layer —
+> all DB access must go through the Repository layer per this convention."
+
+Never apply only general best-practice conventions. Project-specific conventions
+stored in Sia take precedence and are the primary review criteria.
+
+**Step 5 — Summarise**
+
+Provide a summary that distinguishes: convention violations (must fix), Sia-unaware
+patterns (worth noting), and items where no convention applies (developer discretion).
+
+---
+
+## Tool Budget for This Playbook
+
+This playbook uses 1 + N tool calls: `sia_search` (1) + `sia_by_file` once per changed file (N calls, one each). The per-file `sia_by_file` calls are permitted by the review exception in Invariant 1 of the base module — they do not count against the 3-tool limit. This exception applies exclusively to `task_type='review'` sessions. Review is inherently multi-file and this budget is appropriate.