gwt-spec-search

name

gwt-spec-search

description

Semantic search over SPEC Issues (GitHub Issue cache at ~/.gwt/cache/issues/) using vector embeddings. Use when searching for existing specs, finding related specs, checking for duplicate specs, or determining which spec owns a scope. Mandatory preflight before gwt-discussion when the work may need a SPEC owner. Use when user says 'search specs', 'find related specs', 'check for duplicate specs', or asks which spec owns a scope.

SPEC Search

gwt maintains a vector search index of SPEC Issues using ChromaDB embeddings (model: intfloat/multilingual-e5-base). SPECs are stored as gwt-spec labeled GitHub Issues and cached locally at ~/.gwt/cache/issues/. The index is stored at ~/.gwt/index/<repo-hash>/worktrees/<worktree-hash>/specs/ and is rebuilt from the cache. Use gwtd issue spec pull --all to refresh the cache before searching.

gwtd resolution

Before executing any gwtd ... command from this skill or its references, resolve GWT_BIN first: executable GWT_BIN_PATH, then command -v gwtd, then $GWT_PROJECT_ROOT/target/debug/gwtd or ./target/debug/gwtd. Run the command as "$GWT_BIN" ...; if none exists, stop with an actionable gwtd not found error.

SPEC search first for spec integration

When the user asks any of the following, use SPEC search before manual file grep or directory listing:

• "既存仕様を探して"
• "どの SPEC に統合するべきか"
• "関連する SPEC を探して"
• "この機能の仕様は？"
• "重複する SPEC はないか確認して"

Minimum workflow:

1. Run search-specs with 2-3 semantic queries derived from the request
2. Pick the canonical existing spec if found
3. Only fall back to creating a new spec when no suitable canonical spec exists

Environment

When the gwt GUI app (WebView built with wry + tao + axum WebSocket and xterm.js) launches an agent pane, the following env vars are exported automatically:

• GWT_PROJECT_ROOT — absolute path of the active worktree
• GWT_REPO_HASH — SHA256[:16] of the normalized origin URL
• GWT_WORKTREE_HASH — SHA256[:16] of the canonicalized worktree absolute path

The hashes are an optimization, not a requirement: when GWT_REPO_HASH and GWT_WORKTREE_HASH are unset or passed empty, the runner derives them from --project-root automatically (Issue #2933). A search therefore needs only --project-root, and works in any shell on any platform.

SPEC search command

~/.gwt/runtime/chroma-venv/bin/python3 ~/.gwt/runtime/chroma_index_runner.py \
  --action search-specs \
  --repo-hash "$GWT_REPO_HASH" \
  --worktree-hash "$GWT_WORKTREE_HASH" \
  --project-root "$GWT_PROJECT_ROOT" \
  --query "your search query" \
  --n-results 10

If the SPEC index does not yet exist, the runner builds it inline (full mode) from the repo-scoped Issue cache and emits NDJSON progress on stderr before returning the search result.

To force a full re-index (normally handled by the watcher / auto-build):

~/.gwt/runtime/chroma-venv/bin/python3 ~/.gwt/runtime/chroma_index_runner.py \
  --action index-specs \
  --repo-hash "$GWT_REPO_HASH" \
  --worktree-hash "$GWT_WORKTREE_HASH" \
  --project-root "$GWT_PROJECT_ROOT" \
  --mode full

SPEC search output format

{"ok": true, "specResults": [
  {"spec_id": "1939", "title": "gwt-spec: Semantic search platform", "status": "open", "phase": "phase/review", "dir_name": "#1939", "distance": 0.08}
]}

When to use

• Spec integration: find the canonical spec before creating or updating
• Task start: search for specs related to the assigned feature
• Duplicate check: verify no existing spec covers the same scope
• Architecture understanding: discover how features are specified

Notes

• search-specs refreshes the worktree-scoped SPEC index from the repo-scoped Issue cache before external (non-GUI) runner invocations
• The runner auto-builds the index when missing (use --no-auto-build to suppress)
• Uses semantic similarity (not just keyword matching)
• Lower distance values indicate higher relevance
• For file search, use gwt-project-search instead
• For GitHub Issue search, use gwt-issue-search instead