@ryanstark24/sfgraph-skills 1.1.0

package/skills/sf-security-audit/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: sf-security-audit
+description: Audit FLS, CRUD, sharing, and profile/permission-set access for a field or object.
+triggers:
+  - "FLS"
+  - "who has access"
+  - "sharing rules"
+  - "field-level security"
+  - "permission audit"
+  - "CRUD"
+tools_used:
+  - security_audit
+  - analyze_field
+  - staleness_check
+---
+
+# sf-security-audit
+
+Use when the user asks about who can read or write a field/object, what sharing rules apply, or whether FLS / CRUD is consistent with intent.
+
+## Playbook
+
+1. Resolve the target. Call `analyze_field` if the user gave `SObject.Field`; otherwise treat as SObject-level.
+2. Call `security_audit` with the resolved target. Capture profiles, permission sets, permission set groups, sharing rules (criteria + owner-based), OWD, and any `without sharing` Apex that touches the field.
+3. Build the access matrix: Profile/PSet -> Read / Edit / Delete / View All / Modify All.
+4. Identify sharing exposure: OWD setting, sharing rules expanding access, role-hierarchy inheritance toggles.
+5. Flag risks: `without sharing` Apex selectors, missing `stripInaccessible` / `WITH SECURITY_ENFORCED`, guest user access, Experience Cloud profile reach.
+6. Render the Mermaid access matrix returned by the tool.
+
+## Visualization
+
+Render a **`flowchart LR`** access-flow diagram: Profile/PermissionSet nodes on the left, Permission Set Groups in the middle, the target object/field on the right. Edge style encodes Read/Edit/Delete; colour encodes risk (guest user, Experience Cloud, `without sharing` Apex).
+
+```
+flowchart LR
+  P1[Profile:SystemAdmin] -->|RED| F[(Account.Tier__c)]
+  PSG[PSG:Sales] --> PS[PS:SalesEdit] --> F
+  GU[Profile:Guest]:::risk --> F
+  classDef risk fill:#fcc,stroke:#900
+```
+
+When more than 25 Profiles/PSets have access, collapse to a count table and only diagram the high-risk paths (guest, Experience Cloud, without-sharing).
+
+## Staleness check
+
+Before calling `security_audit`, invoke `staleness_check` for the target org. Permission set/profile assignments change frequently; a stale graph misrepresents access. If the report says stale, surface a warning to the user:
+
+> Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Target** — `SObject` or `SObject.Field`.
+- **Access matrix** — table: Profile / PSet -> R / E / D / VA / MA.
+- **Sharing model** — OWD + sharing rules + role hierarchy.
+- **Apex exposure** — list of `without sharing` classes that touch the target.
+- **Risks** — bullets, severity-tagged.
+- **Mermaid access matrix** — embedded.
+
+## Don't
+
+- Do not propose specific profile / permission set edits; surface the gap and let security own the change.
+- Do not modify any sharing configuration.
+- Do not omit guest user / Experience Cloud findings — they are the highest-risk category.
+- Do not infer encryption status from this audit; that requires `sf-architect-security`.

package/skills/sf-snapshot-compare/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: sf-snapshot-compare
+description: Compare two sfgraph snapshots (or one snapshot against current) to see what changed point-in-time.
+triggers:
+  - "compare snapshots"
+  - "what changed between these snapshots"
+  - "point in time diff"
+  - "rewind"
+  - "show me the state before"
+tools_used:
+  - snapshot_list
+  - snapshot_create
+  - point_in_time_diff
+  - staleness_check
+---
+
+# sf-snapshot-compare
+
+Use when the user wants to compare two named points in time — typically a pre-deploy checkpoint vs current, or two milestone snapshots taken during a release.
+
+## Playbook
+
+1. Call `snapshot_list` for the org. Present available snapshots with their `id`, `label`, `createdAt`, and `kind` (auto/manual).
+2. If the user has not yet taken a snapshot, suggest one of:
+   - **MCP**: invoke `snapshot_create` with a descriptive `name` (e.g. `before-deploy-v42`).
+   - **CLI**: `sfgraph snapshot create --label "before-deploy-v42"` (add `--kind scheduled` if the user is wiring this into cron / GitHub Actions).
+
+   Both write into the same per-org SQLite store. Recommend the CLI form when the user asks "how do I take a snapshot before this deploy?" from a script; recommend the MCP tool when they're already in agent conversation. Stop until they confirm.
+3. Call `staleness_check` for the org. Warn if stale — note: even with a stale ingest, snapshot vs snapshot comparisons are still meaningful, but snapshot vs `current` would be stale-on-stale.
+4. Call `point_in_time_diff(from=snapA, to=snapB | 'current')`. Capture nodes added / removed / changed grouped by metadata category.
+5. Summarise totals by category. For each category, list the top items by impact (e.g. ApexClass changes ranked by fan-in).
+
+## Visualization
+
+Render a **`gitGraph`** showing the snapshot chain with annotated commits encoding added/removed/changed counts.
+
+```
+gitGraph
+  commit id: "snap_pre-deploy"
+  commit id: "snap_mid-sprint" tag: "+12 nodes"
+  commit id: "current" tag: "+3 -1 ~5"
+```
+
+If `gitGraph` isn't supported by the client, fall back to a small **`flowchart LR`** with the two snapshots as nodes and a labelled edge carrying the change counts.
+
+## Staleness check
+
+Before calling `point_in_time_diff` with `to='current'`, invoke `staleness_check` for the org. If the report says stale, surface a warning to the user:
+
+> Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
+
+Then continue with the playbook. Snapshot-to-snapshot diffs are immune to staleness, but a snapshot-to-current diff inherits it.
+
+## Response Shape
+
+- **Snapshots compared** — `from` and `to` with labels + timestamps.
+- **Totals** — `added N`, `removed M`, `changed K`.
+- **Per-category** — table: metadata type / added / removed / changed.
+- **Top changes** — bullet list per category, top 5 by fan-in.
+- **Mermaid gitGraph** — embedded.
+- **Suggested next skill** — typically `sf-what-broke` if the user is post-deploy triaging.
+
+## Don't
+
+- Do not auto-create snapshots without explicit user consent; `snapshot_create` mutates local state.
+- Do not delete or rewrite snapshots; this skill is comparison-only.
+- Do not silently truncate the change list — say when results were capped.
+- Do not pretend a snapshot exists if it doesn't; check `snapshot_list` first.

package/skills/sf-web-explorer/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: sf-web-explorer
+description: Triggers when the user wants to visually explore the ingested graph — "show me the graph", "open the visualiser", "see the relationships", "open the web view", "let me click around".
+triggers:
+  - "show me the graph"
+  - "open the visualiser"
+  - "open the web view"
+  - "see the relationships visually"
+  - "render the whole org"
+tools_used: []
+when_to_use: Visual exploration of an ingested org. Pairs with `analyze_field`, `trace_upstream`, `trace_downstream`, and `cross_layer_flow_map` when the markdown answers are not enough and the user wants to click around.
+---
+
+# sf-web-explorer
+
+The MCP tool surface is great for answering specific questions, but sometimes the user wants to **see** their org — pan, zoom, follow edges by eye. `sfgraph serve` boots a local web visualiser at `http://localhost:7777` for exactly this.
+
+This skill does not call any MCP tool. It instructs the user how to launch the viewer and what to do once it's open.
+
+## Playbook
+
+1. Confirm the org has been ingested (use `staleness_check` if uncertain).
+2. Tell the user to run `sfgraph serve` in a shell. It auto-opens their default browser. Mention `--no-open` if they want to suppress that, and `--port <N>` for an alternate port.
+3. Walk them to the right tab:
+   - **Trace** — for following the dependency neighborhood of a single node. Best after running `trace_upstream` / `trace_downstream` in chat and wanting to keep exploring.
+   - **Overview** — for "what does this org look like at a glance" — hubs, layer counts, freshness.
+   - **Schema** — for SObject / field topology and cross-layer references.
+   - **"Render entire org" button** — for the full 3D force-graph (Obsidian-style). Useful for getting your bearings on an unfamiliar org.
+4. Surface the keyboard shortcuts up front: `L` toggles always-show labels, `F` fits the graph, `Esc` closes panels.
+
+## Suggested workflows
+
+- **Following a field across layers.** Run `analyze_field` in chat → switch to the Schema tab in the web view → pivot to "Render entire org" if you need broader context. The web view's labels for hubs stay visible at any zoom so you don't lose your place.
+- **Onboarding to a new org.** Open the Overview tab first. Identify the top hubs by degree. Then jump to Trace tab on each hub to see what depends on them.
+- **Visualising a `cross_layer_flow_map` result.** The markdown gives you the paths; the Trace tab gives you the picture. Both are useful side-by-side.
+
+## Visualization
+
+No diagram from the skill itself — the visualiser **is** the visualisation. Render a short markdown checklist with the launch command and the tab/shortcut cheatsheet.
+
+```
+- Launch: `sfgraph serve`  (or `sfgraph serve --no-open`)
+- URL:    http://localhost:7777
+- Tabs:   Trace · Overview · Schema · [Render entire org]
+- Keys:   L = labels · F = fit · Esc = close panels
+```
+
+## Security note
+
+The server binds to loopback only by default. Anything else requires `--i-understand-public-bind`. Do not suggest exposing it publicly unless the user explicitly asks.
+
+## Don't
+
+- Do not try to call an MCP tool to "open" the viewer — it's a separate process the user launches in their shell.
+- Do not promise screenshots; this skill doesn't render. The browser does.
+- Do not skip the security note when suggesting non-default flags.

package/skills/sf-what-broke/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: sf-what-broke
+description: Identify what regressed in an org since a recent deploy or snapshot using point-in-time diffs.
+triggers:
+  - "what broke"
+  - "post-deploy regression"
+  - "since deploy"
+  - "what changed since last sync"
+  - "regression triage"
+tools_used:
+  - what_broke
+  - point_in_time_diff
+  - staleness_check
+---
+
+# sf-what-broke
+
+Use when the user is triaging a regression and wants to know which metadata changed between two points in time and which of those changes plausibly explains a reported failure.
+
+## Playbook
+
+1. Establish the two anchors: the "good" snapshot (pre-deploy, last green build, or named checkpoint) and the "bad" anchor (now, post-deploy, or a specific snapshot id). Ask if neither is obvious.
+2. Call `point_in_time_diff` between the two anchors. Note added / removed / modified nodes and edge churn per layer.
+3. Call `what_broke` with the same window plus the user's failure signal (failing test name, error stack, broken UI route). The tool ranks suspect changes by reachability to the failure signal.
+4. Triage in descending suspicion order. For each suspect, summarise the change (what attribute moved) and the dependency path to the failure surface.
+5. Render the Mermaid path-to-failure diagram returned by `what_broke`.
+6. Recommend the smallest revert or follow-up investigation (e.g. "inspect `AccountTrigger.handleInsert` — its SOQL selector lost a filter between snapshot X and Y").
+
+## Visualization
+
+Render a **`flowchart LR`** path-to-failure diagram. Each suspect change is a node on the left; intermediate dependency hops are middle nodes; the failure surface (test, route, error) is the rightmost node. Highlight the top-suspect path with a thicker edge.
+
+```
+flowchart LR
+  S1[ApexClass:AccountTrigger]:::suspect --> H1[Service:AccountSvc] --> F1[Test:AccountTriggerTest]:::fail
+  S2[Flow:AccountAfterUpdate] --> H1
+  classDef suspect fill:#fee,stroke:#c00
+  classDef fail fill:#fcc,stroke:#900,stroke-width:2px
+```
+
+If the suspect set is large (>15 nodes) collapse non-top suspects into a single "other changes" node — readability beats completeness.
+
+## Staleness check
+
+Before calling `what_broke`, invoke `staleness_check` for the target org. If the report says stale, surface a warning to the user:
+
+> Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Window** — from `<snapshot/anchor>` to `<snapshot/anchor>`.
+- **Top suspects** — ordered list with confidence, change summary, and the edge path linking them to the failure.
+- **Other changes in window** — collapsed bullet list, not the focus.
+- **Mermaid path-to-failure** — embedded from tool output.
+- **Next step** — single concrete recommendation.
+
+## Don't
+
+- Do not propose a code fix without first inspecting the suspect change in detail via `sf-cross-layer-trace`.
+- Do not run write operations against the org. This skill only reads the local graph + snapshots.
+- Do not bury the lead — top suspect goes first, not last.
+- Do not invent snapshots that don't exist; if the "good" anchor is unavailable, say so.

package/skills/sf-wip-impact/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: sf-wip-impact
+description: Dry-run the impact of uncommitted local changes against the org graph before you commit.
+triggers:
+  - "dry-run this change"
+  - "what would this PR do"
+  - "local impact"
+  - "uncommitted changes"
+  - "wip impact"
+tools_used:
+  - wip_impact
+  - wip_test_gap
+  - wip_diff
+  - staleness_check
+---
+
+# sf-wip-impact
+
+Use when the user has local edits they haven't committed yet (working tree, staged or unstaged) and wants to see the downstream blast radius and test gaps before deciding whether to commit or push.
+
+## Playbook
+
+1. Confirm the project root. Default to the current working directory; if the user explicitly names another, use that.
+2. Call `staleness_check` for the org linked to this project. Warn if stale.
+3. Call `wip_impact` with default `depth=3`. Capture changed nodes, added nodes (in `full-folder` mode), removed nodes, and the downstream dependent set.
+4. Call `wip_test_gap` to find which impacted nodes have no Apex test coverage. These are the "at risk" set.
+5. Optionally call `wip_diff` for a node-level diff (attribute level) when the user asks "what specifically changed in this file".
+6. Summarise: `changed N`, `added M` (full-folder mode only), `removed K`, `at_risk J without tests`.
+
+## Visualization
+
+Render a **`flowchart LR`** impact graph using the 4-class palette emitted by `wip_impact`:
+
+- `changed` (yellow): the file you edited
+- `added` (green): new nodes
+- `removed` (red, dashed): nodes your diff deletes
+- `dependent` (grey): downstream nodes your change reaches
+
+```
+flowchart LR
+  W1[ApexClass:AccountSvc]:::changed --> D1[ApexClass:AccountCtl]:::dependent
+  W1 --> D2[Flow:Account_OnUpdate]:::dependent
+  W2[ApexClass:NewHelper]:::added
+  W3[ApexClass:OldClass]:::removed
+  classDef changed fill:#ffd
+  classDef added fill:#cfc
+  classDef removed fill:#fdd,stroke-dasharray:4 4
+  classDef dependent fill:#eee
+```
+
+If the dependent set exceeds 40 nodes, summarise per category and skip the diagram.
+
+## Staleness check
+
+Before calling `wip_impact`, invoke `staleness_check` for the linked org. WIP analysis depends on the existing graph being accurate; a stale graph will under-report dependents. If the report says stale, surface a warning to the user:
+
+> Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **TL;DR** — `N changed`, `M added`, `K removed`, `J at-risk without tests`.
+- **Changed nodes** — list with their downstream dependents grouped by edge type.
+- **Test gaps** — bulleted list of impacted classes/methods lacking coverage.
+- **Mermaid impact graph** — embedded.
+- **Suggested next step** — typically `sf-impact-from-diff` after the user commits, or `sf-governor-risk-fix` if Apex was touched.
+
+## Don't
+
+- Do not commit, stage, or modify any file — this skill is read-only against the working tree.
+- Do not extrapolate beyond `depth=3` without the user asking; transitive depth >3 tends to be noise.
+- Do not skip `wip_test_gap`; the gap surface is the main reason to run this skill.
+- Do not pretend coverage exists for added nodes — they cannot have tests yet by definition; flag them explicitly.