hoangnb24/gkg

gkg

If .khuym/onboarding.json is missing or stale for the current repo, stop and invoke khuym:using-khuym first.

Start With The Repo Scout

Do not start with which gkg or any imagined gkg <subcommand> discovery flow.

Run:

node .codex/khuym_status.mjs --json

Use the scout output as the source of truth for this repo:

• gkg_readiness.supported_repo = false: do not force gkg; use the fallback section below.
• gkg_readiness.server_reachable = false: gkg is not ready for query work yet.
• gkg_readiness.project_indexed = false: do not pretend MCP discovery is ready. Hand back to khuym:using-khuym readiness or follow the scout's recommended_action.
• If readiness is green, use MCP tools for discovery. Do not switch back to a CLI-shaped discovery workflow.

In this repo, readiness is exposed through the scout. Treat that as the normal operator path.

What Is Reliable Here

Use gkg as a discovery accelerator, not as a replacement for reading files.

Strong, normal-path tools in this repo:

• list_projects
• index_project
• repo_map
• search_codebase_definitions
• read_definitions

Helper-only tool:

• import_usage

Non-core, lower-confidence tools:

• get_references
• get_definition

The practical rule is simple: use repo_map plus search_codebase_definitions plus read_definitions first, then fall back to local inspection whenever symbol-linking looks thin or suspicious.

Primary Discovery Path

Use this path by default during Khuym planning and other codebase discovery work.

1. repo_map

Use first for unfamiliar areas. It is the best starting point for a compact architecture snapshot.

Use it to answer:

• which directories and files matter for this feature
• which files expose the main definitions in a target area
• how the local repo slice is shaped before deeper reads

When discovery is being written down for planning, save the result or summary to history/<feature>/discovery.md under ## Architecture Snapshot.

2. search_codebase_definitions

Use next to find candidate symbols, classes, functions, constants, or handlers related to the feature.

Good uses:

• find auth entry points
• find route handlers
• find data access helpers
• find existing naming and pattern anchors before proposing a new approach

Keep search terms concrete and code-shaped. Prefer symbol names or narrow domain phrases over prose.

3. read_definitions

Use immediately after search_codebase_definitions to read the strongest matches in full.

This is the main evidence-gathering step. It is usually better than hopping file-to-file manually because it keeps discovery centered on actual definitions instead of filenames alone.

When planning writes formal discovery output, summarize the findings in history/<feature>/discovery.md under ## Existing Patterns.

Tool Guidance

list_projects

Use as a light sanity check when the scout says gkg should work and you want to confirm the repo is present in the index.

Do not treat this as the primary readiness check. The scout comes first.

index_project

Use to refresh an indexed project when the index is stale or after significant repo changes.

Do not use this as the first response to project_indexed = false in the scout unless the surrounding readiness workflow explicitly called for it. In this repo, first-time indexing is surfaced by the scout and typically handled by the scout's recommended action.

import_usage

Use only as a helper for importer discovery.

Good uses:

• find who imports a package or module
• check whether a dependency is used broadly or only in one slice
• identify a likely entry file after a package-level search

Do not use it as a general substitute for repo_map or search_codebase_definitions.

get_references

Treat as non-core and low-confidence in this repo.

Use it only when:

• you already know the exact definition to inspect
• you want a quick inbound-usage hint
• you are prepared to verify the answer with local file reads or rg

If it misses callers, gives a thin set, or returns ambiguous results, fall back immediately to rg -n "<symbol>" and nearby file inspection.

get_definition

Treat as non-core and low-confidence in this repo.

Use it only as a quick jump helper from a known call site to a likely definition. Always confirm with read_definitions or a direct file read before relying on it.

If it cannot resolve the symbol cleanly, do not fight it. Fall back to search_codebase_definitions, read_definitions, and rg.

Khuym Workflow Fit

Use this skill mainly during khuym:planning discovery work.

• repo_map feeds the architecture snapshot.
• search_codebase_definitions plus read_definitions feed the existing-pattern evidence.
• import_usage can help confirm importer spread when that matters to the approach.
• get_references and get_definition are optional spot tools, not the backbone of the workflow.

If planning is producing history/<feature>/discovery.md, keep the saved output concise and evidence-based:

• ## Architecture Snapshot
• ## Existing Patterns
• ## Dependency Notes when importer or caller evidence materially affects the plan

Do not dump raw tool output when a short grounded summary will do.

Practical Fallback Without gkg

If the scout says gkg is unsupported or not ready, use local inspection with rg.

Useful fallbacks:

• file inventory: rg --files
• narrow slice inventory: rg --files | rg 'auth|router|db|queue'
• symbol search: rg -n "MySymbol|myFunction|authMiddleware" .
• importer search: rg -n "^import .*from ['\"].*target|require\\(.*target" .
• definition search: rg -n "export (async )?function|class |const .*=" .

Then read the relevant files directly.

If planning is writing discovery output, note the fallback plainly in history/<feature>/discovery.md, for example:

gkg was unavailable or not ready for this repo/session, so discovery used rg and direct file inspection.

Guardrails

• Do not describe the workflow as gkg repo_map, gkg search, gkg deps, or gkg context. Those are not the discovery interface this repo relies on.
• Do not skip the scout-based readiness check.
• Do not let symbol-linking tools outrank direct file evidence.
• Do not use import_usage as a general architecture mapper.
• Do not rely on get_references or get_definition without a fallback plan.
• Do not skip reading the actual files before code changes.