=== root/.kiro/hooks/gortex-post-edit.json === { "name": "Gortex: Post-Edit Impact Check", "version": "1.0.0", "description": "After saving a source file, runs detect_changes and get_test_targets to show blast radius and which tests to run.", "when": { "type": "fileEdited", "patterns": ["**/*.go", "**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.py", "**/*.rs", "**/*.java", "**/*.kt", "**/*.scala", "**/*.swift", "**/*.rb", "**/*.cs", "**/*.php"] }, "then": { "type": "askAgent", "prompt": "A source file was just edited. Call Gortex detect_changes with scope unstaged to see which symbols were affected and the risk level. If symbols were changed, also call get_test_targets with those symbol IDs to identify which tests should be run. Briefly report the risk level and test commands." } } === root/.kiro/hooks/gortex-pre-read.json === { "name": "Gortex: Enrich File Reads", "version": "1.0.0", "description": "Before reading a source file, calls get_editing_context to inject symbol context, callers, callees, and imports.", "when": { "type": "preToolUse", "toolTypes": ["read"] }, "then": { "type": "askAgent", "prompt": "SKIP this hook entirely (do nothing, proceed with the read) if ANY of these are true: (1) the file path contains .kiro/, .claude/, .github/, .vscode/, or node_modules/, (2) the file extension is .md, .json, .yaml, .yml, .toml, .txt, .lock, .sum, .mod, .env, .gitignore, .html, .css, or .svg, (3) the file is not a source code file. ONLY for source code files (.go, .ts, .tsx, .js, .jsx, .py, .rs, .java, .kt, .cs, .rb, .php, .swift, .scala, .c, .cpp, .h): call get_editing_context or get_file_summary for the file to get symbol context before reading it." } } === root/.kiro/hooks/gortex-smart-context.json === { "name": "Gortex: Smart Context on Prompt", "version": "1.0.0", "description": "On each new prompt, calls smart_context to assemble task-relevant code context from the knowledge graph in one shot.", "when": { "type": "promptSubmit" }, "then": { "type": "askAgent", "prompt": "If the user's message describes a coding task (adding a feature, fixing a bug, refactoring, understanding code), call Gortex's smart_context tool with the task description to get relevant symbols, source code, relationships, and an edit plan in one call. Skip this for non-coding questions or simple chat." } } === root/.kiro/settings/mcp.json === { "mcpServers": { "gortex": { "args": [ "mcp" ], "autoApprove": [ "graph_stats", "search_symbols", "winnow_symbols", "get_symbol", "get_file_summary", "get_editing_context", "get_dependencies", "get_dependents", "get_call_chain", "get_callers", "find_implementations", "find_usages", "get_cluster", "get_symbol_source", "batch_symbols", "find_import_path", "explain_change_impact", "get_recent_changes", "smart_context", "get_edit_plan", "get_test_targets", "suggest_pattern", "get_communities", "get_processes", "detect_changes", "index_repository", "reindex_repository", "verify_change", "check_guards", "prefetch_context", "analyze", "diff_context", "index_health", "get_symbol_history", "scaffold", "batch_edit", "contracts", "feedback", "save_note", "query_notes", "distill_session", "store_memory", "query_memories", "surface_memories" ], "command": "gortex", "disabled": false, "env": { "GORTEX_INDEX_WORKERS": "8" } } } } === root/.kiro/steering/gortex-debug.md === --- inclusion: manual --- # Debugging with Gortex ## Workflow 1. `search_symbols({query: ""})` — find related symbols 2. `get_callers({id: ""})` — who calls it? 3. `get_call_chain({id: ""})` — what does it call? 4. `get_editing_context({path: ""})` — full file context 5. `get_process({id: ""})` — trace execution flow ## Debugging patterns | Symptom | Gortex Approach | | -------------------- | --------------- | | Error message | `search_symbols` for error-related names, then `get_callers` on throw sites | | Wrong return value | `get_call_chain` on the function, trace callees for data flow | | Intermittent failure | `get_editing_context`, look for external calls and async deps | | Performance issue | `find_usages`, find symbols with many callers (hot paths) | | Recent regression | `detect_changes`, see what your changes affect | === root/.kiro/steering/gortex-explore.md === --- inclusion: manual --- # Exploring Codebases with Gortex ## Workflow 1. `index_health` — confirm the index is ready (`graph_stats` for node/edge counts) 2. `get_communities` — see functional clusters (architecture overview) 3. `search_symbols({query: ""})` — find symbols related to a concept 4. `get_processes` — discover execution flows 5. `get_process({id: ""})` — trace a specific flow step by step 6. `get_editing_context({path: ""})` — deep dive on a specific file ## When to use - "How does authentication work?" - "What's the project structure?" - "Show me the main components" - Understanding code you haven't seen before ## Key tools - `get_communities` for architectural overview (functional clusters with cohesion scores) - `get_processes` for execution flow discovery (entry points to call chains) - `search_symbols` for concept-based symbol search (BM25 + camelCase-aware) - `get_editing_context` for 360-degree file view (symbols, callers, callees, imports) === root/.kiro/steering/gortex-impact.md === --- inclusion: manual --- # Impact Analysis with Gortex ## Workflow 1. `search_symbols({query: "X"})` — find the symbol ID 2. `explain_change_impact({ids: ", "})` — risk-tiered blast radius 3. `get_dependents({id: "", depth: 3})` — detailed dependent tree 4. `detect_changes({scope: "staged"})` — pre-commit check ## Risk tiers | Depth | Risk Level | Meaning | | ----- | -------------- | ------------------------ | | d=1 | WILL BREAK | Direct callers/importers | | d=2 | LIKELY AFFECTED| Indirect dependencies | | d=3 | MAY NEED TESTING| Transitive effects | ## Before any non-trivial change - Call `explain_change_impact` with all symbols you plan to modify - Review the risk level (LOW/MEDIUM/HIGH/CRITICAL) - Check `by_depth`: d=1 items WILL BREAK - Note `affected_processes` and `affected_communities` - Check `test_files` that need re-running - Before commit: `detect_changes` to verify scope === root/.kiro/steering/gortex-refactor.md === --- inclusion: manual --- # Refactoring with Gortex ## Workflow 1. `search_symbols({query: "X"})` — find the symbol ID 2. `explain_change_impact({ids: ""})` — map blast radius 3. `get_editing_context({path: ""})` — see all symbols and relationships 4. `find_usages({id: ""})` — every reference to change 5. `get_edit_plan({ids: ""})` — dependency-ordered edit sequence 6. Edit in order: interfaces -> implementations -> callers -> tests 7. `detect_changes({scope: "all"})` — verify after changes ## Rename symbol - `find_usages` to get every reference location - `explain_change_impact` to assess blast radius - Edit in dependency order: definition, then callers, then tests ## Extract module - `get_editing_context` on the source file to see all symbols - `get_dependents` on symbols to extract to find external callers - `find_import_path` for correct import paths in the new location ## Split function/service - `get_call_chain` to understand all callees - `get_callers` to map all call sites that need updating - `explain_change_impact` for full blast radius === root/.kiro/steering/gortex-workflow.md === --- inclusion: always --- # Gortex Code Intelligence Gortex is running as an MCP server. It indexes this repository into an in-memory knowledge graph and exposes tools for code navigation, impact analysis, and refactoring. ## MANDATORY: Use Gortex tools instead of file reads You **MUST** prefer Gortex graph queries over file reads on every task in this repo. These are not suggestions — the tools below replace the corresponding read/grep flows. From a shell (no MCP tools), every tool below is reachable as `gortex call --arg k=v` (e.g. `gortex call read_file --arg path=`) — there is no bare `gortex ` verb. ### Navigation and Reading | Instead of... | Use... | |---------------------------------------|------------------------------------------| | Reading a whole file for one function | `get_symbol_source` with `id: "path/to/file.go::SymbolName"` (methods carry the receiver: `"path/to/file.go::Recv.Name"`; 80% fewer tokens) — use `get_file_summary` first if you don't know the symbol name | | Reading to find a function | `get_symbol` or `get_editing_context` | | Multiple `get_symbol` calls | `batch_symbols` (one call for N symbols) | | Searching for references | `find_usages` (zero false positives) | | Searching to find a symbol by name | `search_symbols` (BM25 + camelCase) | | Filtering `search_symbols` by hand | `winnow_symbols` — structured constraint chain (kind, language, community, path_prefix, min_fan_in, min_churn) with per-axis score contributions | | Reading to understand a file | `get_file_summary` or `get_editing_context` | | Reading multiple files to trace calls | `get_call_chain` / `get_callers` | | Guessing an import path | `find_import_path` | | Reading to check a function signature | `get_symbol_signature` | | 5-10 calls to explore for a task | `smart_context` (one call) | ### Impact Analysis and Safety | Instead of... | Use... | |---------------------------------------|------------------------------------------| | Reading files to assess change scope | `explain_change_impact` (includes cross-community warnings) | | Guessing which tests to run | `get_test_targets` | | Manual dependency ordering | `get_edit_plan` | | Hoping signature changes are safe | `verify_change` — checks callers and interface implementors | | Manually checking team conventions | `check_guards` — evaluates guard rules from .gortex.yaml | | Wondering if a new dep creates a cycle| `analyze` with `kind: "would_create_cycle"` — checks before you add it | ### Structural Code Search | Instead of... | Use... | |------------------------------------------|------------------------------------------| | Grep for an anti-pattern in this repo | `search_ast` with `detector: ""` (`error-not-wrapped` / `sql-string-concat` / `weak-crypto` / `panic-in-library` / `goroutine-without-recover` / `http-client-no-timeout` / `hardcoded-secret` / `empty-catch` / `java-string-equality` / `python-mutable-default-arg`). Cross-language; matches enriched with enclosing `symbol_id`. | | Grep for a code shape | `search_ast` with `pattern: "..."` + `language` (tree-sitter S-expression; capture with `@name`, anchor with `@match`). | | Scoping audit to important code | Pass `min_fan_in_of_enclosing_func: ` — drops matches in functions with fewer than N callers. | ### Diagnostics and Code Actions | Instead of... | Use... | |------------------------------------------|------------------------------------------| | Polling for diagnostics after every edit | `subscribe_diagnostics` — opt into push `notifications/diagnostics`. Initial state replays as `initial_replay: true`; thereafter delta-changed files only. `min_severity` / `path_prefix` filters scope the stream. | | Manual diagnostics fetch | `get_diagnostics` — last stored `publishDiagnostics` for a file; `wait` + `timeout_ms` block until the first publish. | | Forgetting to opt out | `unsubscribe_diagnostics` — idempotent; auto-fires on session disconnect. | | Hand-applying compiler suggestions | `get_code_actions` then `apply_code_action` (atomic temp+rename, both `changes` and `documentChanges`). | | Walking a file to apply every fix | `fix_all_in_file` — one-shot `source.fixAll` for the whole file. | ### Code Quality and Analysis | Instead of... | Use... | |---------------------------------------|------------------------------------------| | Manually hunting unused code | `analyze` with `kind: "dead_code"` — zero incoming edges (excludes entry points, tests, exports) | | Guessing which symbols are over-coupled| `analyze` with `kind: "hotspots"` — ranks by fan-in, fan-out, community crossings | | Manually scanning for circular deps | `analyze` with `kind: "cycles"` — Tarjan's SCC with severity classification | | Surveying K8s manifests in the repo | `analyze` with `kind: "k8s_resources"` — KindResource fan-out (depends_on / configures / mounts / exposes / uses_env); `k8s_kind` / `namespace` / `name` filters | | Listing container images in use | `analyze` with `kind: "images"` — KindImage with consumer count (Dockerfile FROM + K8s `container.image`); `role` / `ref` / `tag` filters | | Mapping the Kustomize overlay tree | `analyze` with `kind: "kustomize"` — KindKustomization with base / resource fan-out; `dir` filter | | Auditing what crosses repo boundaries | `analyze` with `kind: "cross_repo"` — calls / implements / extends edges crossing repo boundaries, grouped by source → target repo; `repo` / `base_kind` / `path_prefix` filters | | Surveying dbt / SQLMesh models | `analyze` with `kind: "dbt_models"` — dbt / SQLMesh models, seeds, snapshots, sources with column count + lineage fan-in/out; `framework` / `type` / `materialized` / `name` filters | | Checking if the index is stale | `index_health` — health score, parse failures, stale files | | Wondering what changed this session | `get_symbol_history` — modification counts, flags churning (3+ edits) | ### Code Generation and Editing | Instead of... | Use... | |---------------------------------------|------------------------------------------| | Reading files to learn a pattern | `suggest_pattern` | | Manually scaffolding from a pattern | `scaffold` — generates code, wiring, and test stubs from an example | | Sequencing multi-file edits yourself | `batch_edit` — applies edits in dependency order, re-indexes between steps | | Reading a diff without graph context | `diff_context` — enriches git diff with callers, callees, community, risk | | Guessing what context you need next | `prefetch_context` — predicts needed symbols from task + recent activity | ### Dataflow (CPG-lite) | Instead of... | Use... | |---------------------------------------|------------------------------------------| | Hand-tracing a value through helpers | `flow_between(source_id, sink_id, max_depth=8)` — ranked dataflow paths over `value_flow` ∪ `arg_of` ∪ `returns_to` | | Grepping for sources / sinks | `taint_paths(source_pattern, sink_pattern)` — pattern sweep. Patterns: bare = name substring; `exact:Foo`; `path:dir/`; `kind:method`. Sinks auto-expand functions to params. | ### Clone Detection | Instead of... | Use... | |---------------------------------------|------------------------------------------| | Eyeballing the repo for copy-paste | `find_clones` — near-duplicate function/method clusters from the `similar_to` graph layer (MinHash + LSH; catches renamed-variable clones) | | Finding safe-to-delete duplicates | `find_clones` with `dead_only: true` — clusters containing a dead-code symbol ("dead duplicates of live code") | ### Multi-Repo Management | Instead of... | Use... | |---------------------------------------|------------------------------------------| | Manually adding a repo to config | `track_repository` — indexes immediately, persists to config | | Manually removing a repo from config | `untrack_repository` — evicts nodes/edges, persists to config | | Refreshing the graph after edits | `reindex_repository` — incremental re-index of changed files only; pass `paths` to scope | | Wondering which project is active | `get_active_project` — returns project name and repo list | | Switching project context | `set_active_project` — re-scopes all subsequent queries | | Scoping a query to one repo | Pass `repo` param to `search_symbols`, `find_usages`, etc. | | Scoping a query to a project | Pass `project` param to any query tool | | Filtering by reference tag | Pass `ref` param to any query tool | ### Session Memory (save_note / query_notes / distill_session) Gortex remembers code; this triplet remembers **why you made a call**. Notes persist per-repo across daemon restarts and context compactions, are scoped to the session's workspace, and are auto-linked to symbols mentioned in the body. | Trigger | Use | |----------------------------------------------------------|--------------------------------------------------------------------------------| | Session start in a touched repo (after a compaction or on a fresh run) | `distill_session` — returns top symbols, pinned notes, decisions, recent excerpts. Seed your mental model before reading any file. | | Making a decision, rejecting an alternative, hitting a non-obvious constraint, committing to an invariant | `save_note tags:"decision" body:""` — mention symbol IDs (`pkg/foo.go::Bar`) in the body for auto-linking; pin (`pinned:true`) anything load-bearing. | | Before editing a symbol you've touched before | `query_notes symbol_id:""` — surfaces prior decisions and warnings attached to that symbol. | Save: decisions, non-obvious constraints, follow-ups, bug reproductions, surprising findings, partial-progress hand-offs. Skip: play-by-play of what you just did (the diff says it), patterns derivable from the graph, anything already in the steering docs. Canonical tags: `decision`, `bug`, `follow-up`, `gotcha`, `invariant`. ### Development Memories (store_memory / query_memories / surface_memories) `save_note` is a **per-session scratchpad**; `store_memory` is the **workspace-wide durable knowledge base** — entries outlive sessions, agents, and teammates so every future agent in the workspace inherits them. | Trigger | Use | |----------------------------------------------------------|--------------------------------------------------------------------------------| | Immediately after `smart_context` (every new task) | `surface_memories task:"" symbol_ids:""` — memories ranked by anchor overlap, importance, pinning, recency. Each hit carries `match_reasons`. | | You discover a durable invariant / gotcha / decision worth teaching the team | `store_memory kind:"" body:"" symbol_ids:"" importance:5` — pin load-bearing memories. | | A memory is no longer true | `store_memory body:"" supersedes:""` — preserves audit trail; old memory hidden by default. | Store: invariants, conventions, incident learnings, API contracts not enforced by types, debugging traps, cross-cutting decisions. Skip: anything derivable from code, session-local play-by-play (use `save_note`), steering-doc content. ## Session workflow 1. Call `index_health` to confirm Gortex is running and indexed (`graph_stats` for counts). If `total_nodes` is 0, call `index_repository` with path `"."`. 2. Call `distill_session` to recover prior session memory for this workspace. 3. In multi-repo mode, call `get_active_project` to check scope. Use `set_active_project` to switch if needed. 4. For a new task, call `smart_context` with the task description. Immediately after, call `surface_memories` with the same task description and the top symbol hits. 5. Before editing any file, call `get_editing_context` first. If you've touched the symbol before, also call `query_notes symbol_id:""` and `query_memories symbol_id:""`. 6. Before changing a function signature, call `verify_change` to catch contract violations — checks callers across all repos. 7. Before any refactor, call `get_edit_plan` for dependency-ordered file list. Use `batch_edit` to apply atomically. 8. Verify with the project's real build/test. Reserve `check_guards` for guard-relevant changes and `get_test_targets` to find the tests covering a substantive change (includes cross-repo test files). 9. After making a meaningful decision or hitting a non-obvious constraint, call `save_note` so the next session can recover it. If the discovery is workspace-wide and worth teaching the team, call `store_memory` instead — that compounds across sessions. 10. Before committing, call `detect_changes` to verify scope. Use `diff_context` for graph-enriched review.