zzet--gortex/internal/agents/kiro/content.go

// Package kiro implements the Gortex init integration for Kiro
// IDE. Writes:
//
//   - .kiro/settings/mcp.json    (MCP server stanza, merged)
//   - .kiro/steering/gortex-*.md (steering docs, static)
//   - .kiro/hooks/gortex-*.json  (agent hooks, static)
package kiro

// SteeringFiles maps filename → content under .kiro/steering/. The
// "workflow" doc has inclusion: always; the others are manual
// (surfaced only when the user asks for them).
var SteeringFiles = map[string]string{
	"gortex-workflow.md": steeringWorkflow,
	"gortex-explore.md":  steeringExplore,
	"gortex-debug.md":    steeringDebug,
	"gortex-impact.md":   steeringImpact,
	"gortex-refactor.md": steeringRefactor,
}

// HookFiles maps filename → content under .kiro/hooks/. Each file
// is a Kiro agent-hook definition (when+then JSON).
var HookFiles = map[string]string{
	"gortex-smart-context.json": hookSmartContext,
	"gortex-post-edit.json":     hookPostEdit,
	"gortex-pre-read.json":      hookPreRead,
}

const steeringWorkflow = `---
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 <tool> --arg k=v`" + ` (e.g. ` + "`gortex call read_file --arg path=<file>`" + `) — there is no bare ` + "`gortex <tool>`" + ` 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: \"<name>\"`" + ` (` + "`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: <N>`" + ` — 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:\"<what+why>\"`" + ` — 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:\"<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:\"<task>\" symbol_ids:\"<top hits>\"`" + ` — 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:\"<invariant|gotcha|convention|decision>\" body:\"<what+why>\" symbol_ids:\"<id>\" importance:5`" + ` — pin load-bearing memories. |
| A memory is no longer true                                | ` + "`store_memory body:\"<corrected>\" supersedes:\"<old-id>\"`" + ` — 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:\"<id>\"`" + ` and ` + "`query_memories symbol_id:\"<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.
`

const steeringExplore = `---
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: \"<concept>\"})`" + ` — find symbols related to a concept
4. ` + "`get_processes`" + ` — discover execution flows
5. ` + "`get_process({id: \"<process-id>\"})`" + ` — trace a specific flow step by step
6. ` + "`get_editing_context({path: \"<file>\"})`" + ` — 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)
`

const steeringDebug = `---
inclusion: manual
---

# Debugging with Gortex

## Workflow

1. ` + "`search_symbols({query: \"<error or suspect>\"})`" + ` — find related symbols
2. ` + "`get_callers({id: \"<suspect>\"})`" + ` — who calls it?
3. ` + "`get_call_chain({id: \"<suspect>\"})`" + ` — what does it call?
4. ` + "`get_editing_context({path: \"<file>\"})`" + ` — full file context
5. ` + "`get_process({id: \"<process>\"})`" + ` — 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 |
`

const steeringImpact = `---
inclusion: manual
---

# Impact Analysis with Gortex

## Workflow

1. ` + "`search_symbols({query: \"X\"})`" + ` — find the symbol ID
2. ` + "`explain_change_impact({ids: \"<id1>, <id2>\"})`" + ` — risk-tiered blast radius
3. ` + "`get_dependents({id: \"<symbol-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
`

const steeringRefactor = `---
inclusion: manual
---

# Refactoring with Gortex

## Workflow

1. ` + "`search_symbols({query: \"X\"})`" + ` — find the symbol ID
2. ` + "`explain_change_impact({ids: \"<id>\"})`" + ` — map blast radius
3. ` + "`get_editing_context({path: \"<file>\"})`" + ` — see all symbols and relationships
4. ` + "`find_usages({id: \"<id>\"})`" + ` — every reference to change
5. ` + "`get_edit_plan({ids: \"<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
`

const hookSmartContext = `{
  "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."
  }
}
`

const hookPostEdit = `{
  "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."
  }
}
`

const hookPreRead = `{
  "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."
  }
}
`

// AutoApproveTools is the list of Gortex MCP tools Kiro should
// auto-approve without prompting. Baked into the mcp.json entry so
// the user isn't interrupted for every query call.
var AutoApproveTools = []string{
	"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",
}