diff --git a/docs/sdd-search-strategy.md b/docs/sdd-search-strategy.md new file mode 100644 index 000000000..0b16308e4 --- /dev/null +++ b/docs/sdd-search-strategy.md @@ -0,0 +1,50 @@ +# SDD Search Strategy Design Boundary + +This change makes code search configurable for SDD code-reading phases while keeping `grep` as the safe default. RAG/MCP search is an optional acceleration path, not a hard dependency. + +## Detection contract + +`sdd-init` resolves `search_strategy` in this order: + +1. Explicit agent/system config wins. +2. `openspec/config.yaml` wins when present. +3. MCP auto-detection MAY enable `hybrid` only when a tool name or description explicitly indicates semantic, vector, or embedding-based code search. +4. If nothing qualifies, the mode is `grep`. + +Generic tools named like `code_search` are not enough by themselves; their description must indicate embedding-backed semantic search to avoid false positives. + +## Fallback behavior + +| Situation | Behavior | +|-----------|----------| +| No `search_strategy` config | Use `grep` mode. | +| `mode: grep` | Use the existing Grep + targeted Read flow. | +| `mode: hybrid` with valid RAG tool | Query RAG first, then fall back to grep if results are insufficient. | +| RAG tool missing, down, or timing out | Log the issue, use grep for the rest of the phase, and report the risk. | +| Optional reindex fails after `sdd-apply` | Continue; reindex is non-blocking. | + +## Why `grep` remains the safe default + +`grep` is deterministic, local, and already supported by every SDD phase. Keeping it as the default preserves backwards compatibility and avoids making SDD depend on optional MCP infrastructure. + +`hybrid` mode is useful when available because semantic search can reduce exploration work on large codebases, but correctness still comes from the fallback cascade: RAG → grep → targeted read. + +## Baseline measurement on this repository + +Measured locally on `gentle-ai` using a grep-style scan over tracked UTF-8 files. + +| Scenario | Scope | Files scanned | Lines scanned | Matches | Time | +|----------|-------|---------------|---------------|---------|------| +| Find orchestrator forwarding contract (`Search Strategy Forwarding`) | `internal/assets/*/sdd-orchestrator.md` | 11 | 2,944 | 11 | 1.768 ms | +| Find search strategy contract (`search_strategy`) | `internal/assets/skills/**` | 33 | 4,532 | 23 | 3.102 ms | +| Find fallback wording (`fall back to grep`) | `internal/assets/skills/**` | 33 | 4,532 | 1 | 1.850 ms | + +These numbers are intentionally a baseline, not a promise of RAG performance. They show the current grep path is cheap for this repository slice, while documenting the exact metrics future `hybrid` runs should compare against: files scanned, lines read, matching confidence, fallback activation, and elapsed time. + +## Review checklist + +- [ ] `search_strategy` detection is explicit and conservative. +- [ ] Missing or broken RAG never blocks SDD execution. +- [ ] `grep` remains the default when config is absent. +- [ ] Orchestrators forward search config to `sdd-explore`, `sdd-apply`, and `sdd-verify`. +- [ ] Tests cover the contract so future asset edits cannot silently remove it. diff --git a/internal/assets/antigravity/sdd-orchestrator.md b/internal/assets/antigravity/sdd-orchestrator.md index bcabb1e68..0a8f7c31c 100644 --- a/internal/assets/antigravity/sdd-orchestrator.md +++ b/internal/assets/antigravity/sdd-orchestrator.md @@ -205,6 +205,17 @@ When executing `sdd-apply` or `sdd-verify` phases, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When executing `sdd-apply` for a continuation batch (not the first batch): diff --git a/internal/assets/assets_test.go b/internal/assets/assets_test.go index 348f88ca5..83d7df8fd 100644 --- a/internal/assets/assets_test.go +++ b/internal/assets/assets_test.go @@ -412,6 +412,78 @@ func TestSDDPhaseCommonEnforcesExecutorBoundary(t *testing.T) { } } +func TestSDDSearchStrategyContract(t *testing.T) { + orchestrators := []string{ + "generic/sdd-orchestrator.md", + "claude/sdd-orchestrator.md", + "opencode/sdd-orchestrator.md", + "gemini/sdd-orchestrator.md", + "codex/sdd-orchestrator.md", + "cursor/sdd-orchestrator.md", + "windsurf/sdd-orchestrator.md", + "antigravity/sdd-orchestrator.md", + "kiro/sdd-orchestrator.md", + "kimi/sdd-orchestrator.md", + "qwen/sdd-orchestrator.md", + } + + for _, assetPath := range orchestrators { + t.Run(assetPath, func(t *testing.T) { + content := MustRead(assetPath) + for _, want := range []string{ + "Search Strategy Forwarding (MANDATORY)", + "sdd-explore", "sdd-apply", "sdd-verify", + `mem_search(query: "sdd-init/{project}"`, + "SEARCH STRATEGY CONFIG DETECTED", + "Section F", + "grep", + } { + if !strings.Contains(content, want) { + t.Fatalf("%q missing search strategy contract %q", assetPath, want) + } + } + }) + } + + phaseCommon := MustRead("skills/_shared/sdd-phase-common.md") + for _, want := range []string{ + "## F. Code Search Protocol", + "`grep` | Current behavior", + "`hybrid` | RAG-first cascade with grep fallback", + "If `mode` is `hybrid` but `rag.mcp_tool` is missing or empty, fall back to `grep`", + "If `mode` is `hybrid` but the MCP tool call fails", + "grep fallback guarantees correctness", + } { + if !strings.Contains(phaseCommon, want) { + t.Fatalf("sdd-phase-common missing search strategy boundary %q", want) + } + } + + initSkill := MustRead("skills/sdd-init/SKILL.md") + for _, want := range []string{ + "Resolve `search_strategy` from agent marker", + "semantic/vector/embedding", + "no qualifying RAG MCP tool", + "Search Strategy status", + } { + if !strings.Contains(initSkill, want) { + t.Fatalf("sdd-init missing search strategy detection contract %q", want) + } + } + + applySkill := MustRead("skills/sdd-apply/SKILL.md") + for _, want := range []string{ + "3a. Read `search_strategy`", + "3b. Read existing code", + "#### Step 6b: Reindex Hook (Section F)", + "cached in Step 3a", + } { + if !strings.Contains(applySkill, want) { + t.Fatalf("sdd-apply missing search strategy apply contract %q", want) + } + } +} + func TestOpenCodeSDDOverlaySubagentsAreExplicitExecutors(t *testing.T) { for _, assetPath := range []string{"opencode/sdd-overlay-single.json", "opencode/sdd-overlay-multi.json"} { t.Run(assetPath, func(t *testing.T) { diff --git a/internal/assets/claude/sdd-orchestrator.md b/internal/assets/claude/sdd-orchestrator.md index af764242c..74e75d789 100644 --- a/internal/assets/claude/sdd-orchestrator.md +++ b/internal/assets/claude/sdd-orchestrator.md @@ -217,6 +217,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/internal/assets/codex/sdd-orchestrator.md b/internal/assets/codex/sdd-orchestrator.md index 009ea6e2f..5e0ea260d 100644 --- a/internal/assets/codex/sdd-orchestrator.md +++ b/internal/assets/codex/sdd-orchestrator.md @@ -197,6 +197,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/internal/assets/cursor/sdd-orchestrator.md b/internal/assets/cursor/sdd-orchestrator.md index a211a9de6..19c39bf1b 100644 --- a/internal/assets/cursor/sdd-orchestrator.md +++ b/internal/assets/cursor/sdd-orchestrator.md @@ -237,6 +237,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/internal/assets/gemini/sdd-orchestrator.md b/internal/assets/gemini/sdd-orchestrator.md index b294f58d0..878fa5f88 100644 --- a/internal/assets/gemini/sdd-orchestrator.md +++ b/internal/assets/gemini/sdd-orchestrator.md @@ -197,6 +197,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/internal/assets/generic/sdd-orchestrator.md b/internal/assets/generic/sdd-orchestrator.md index 2edf907b8..0c9e9d2f7 100644 --- a/internal/assets/generic/sdd-orchestrator.md +++ b/internal/assets/generic/sdd-orchestrator.md @@ -215,6 +215,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/internal/assets/kimi/sdd-orchestrator.md b/internal/assets/kimi/sdd-orchestrator.md index 1ddea9c3a..7f2b65dcc 100644 --- a/internal/assets/kimi/sdd-orchestrator.md +++ b/internal/assets/kimi/sdd-orchestrator.md @@ -153,6 +153,14 @@ Sub-agents get a fresh context with NO memory. The orchestrator controls context | `sdd-verify` | spec + tasks | `verify-report` | | `sdd-archive` | all artifacts | `archive-report` | +### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify`, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block, add: `"SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search."` +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F) + ### Engram Topic Key Format | Artifact | Topic Key | diff --git a/internal/assets/kiro/sdd-orchestrator.md b/internal/assets/kiro/sdd-orchestrator.md index dacf8e913..9ee82b1f9 100644 --- a/internal/assets/kiro/sdd-orchestrator.md +++ b/internal/assets/kiro/sdd-orchestrator.md @@ -193,6 +193,17 @@ When executing `sdd-apply` or `sdd-verify` phases: Resolve TDD status ONCE per session (at first apply/verify phase) and cache it. +### Search Strategy Forwarding (MANDATORY) + +When executing `sdd-explore`, `sdd-apply`, or `sdd-verify` phases: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to your working context: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, proceed with grep per Section F. + +Resolve this ONCE per session (at first explore/apply/verify phase) and cache it. + ### Apply-Progress Continuity (MANDATORY) When starting a continuation `sdd-apply` batch (not the first batch for a change): diff --git a/internal/assets/opencode/sdd-orchestrator.md b/internal/assets/opencode/sdd-orchestrator.md index fa3233fac..afb09d7c5 100644 --- a/internal/assets/opencode/sdd-orchestrator.md +++ b/internal/assets/opencode/sdd-orchestrator.md @@ -210,6 +210,14 @@ When launching `sdd-apply` or `sdd-verify`, the orchestrator MUST: 2. If the result contains `strict_tdd: true`, add: `"STRICT TDD MODE IS ACTIVE. Test runner: {test_command}. You MUST follow strict-tdd.md. Do NOT fall back to Standard Mode."` 3. If the search fails or `strict_tdd` is not found, do NOT add the TDD instruction +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify`, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block, add: `"SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search."` +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F) + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch: diff --git a/internal/assets/qwen/sdd-orchestrator.md b/internal/assets/qwen/sdd-orchestrator.md index 41d1a2e8c..e63d73c2f 100644 --- a/internal/assets/qwen/sdd-orchestrator.md +++ b/internal/assets/qwen/sdd-orchestrator.md @@ -197,6 +197,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/internal/assets/skills/_shared/persistence-contract.md b/internal/assets/skills/_shared/persistence-contract.md index f0de6eafd..8632e4162 100644 --- a/internal/assets/skills/_shared/persistence-contract.md +++ b/internal/assets/skills/_shared/persistence-contract.md @@ -87,6 +87,20 @@ Why this split: - Sub-agents read for SDD: SDD artifacts are large; inlining them in the orchestrator prompt would consume the entire context window - Sub-agents always write: they have the complete detail on what happened; nuance is lost by the time results flow back to the orchestrator +## Search Strategy Context + +The orchestrator MAY pass `search_strategy` config to sub-agents that read code. This is optional — phases MUST default to `grep` behavior when absent. + +```yaml +search_strategy: + mode: grep | hybrid # default: grep (current behavior) + rag: # present only when mode: hybrid + mcp_tool: "tool_name" # MCP tool name for semantic search (REQUIRED for hybrid) + reindex_tool: "tool_name" # optional — fire-and-forget after sdd-apply batch +``` + +Sub-agents that receive this config follow **Section F** from `sdd-phase-common.md` for code search. Sub-agents that do NOT read code (sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-archive) ignore this config entirely. + ## Orchestrator Prompt Instructions for Sub-Agents Non-SDD: diff --git a/internal/assets/skills/_shared/sdd-phase-common.md b/internal/assets/skills/_shared/sdd-phase-common.md index eb7841cfd..2226d3ed5 100644 --- a/internal/assets/skills/_shared/sdd-phase-common.md +++ b/internal/assets/skills/_shared/sdd-phase-common.md @@ -105,3 +105,62 @@ SDD must protect reviewer cognitive load, not only generate tasks. - In a Feature Branch Chain, PR #1 targets the feature/tracker branch and later child PRs target the immediate previous PR branch; if GitHub shows previous slices in a child diff, retarget/rebase until the diff is clean. This guard exists to reduce reviewer burnout and keep implementation delivery safe. Do not treat it as optional process noise. + +## F. Code Search Protocol + +Phases that investigate or read existing code (`sdd-explore`, `sdd-apply`, `sdd-verify`) MUST follow this protocol instead of ad-hoc Grep+Read. + +### Reading the config + +``` +Read search_strategy from project context: +├── engram: included in sdd-init/{project} observation → search_strategy block +├── openspec: openspec/config.yaml → search_strategy key +└── Not found → default to mode=grep (current behavior, zero change) +``` + +### Mode behavior + +| Mode | Behavior | +|------|----------| +| `grep` | Current behavior — Grep + Read. No RAG tool calls. Default when config is absent. | +| `hybrid` | RAG-first cascade with grep fallback. Requires `search_strategy.rag.mcp_tool`. | + +If `mode` is `hybrid` but `rag.mcp_tool` is missing or empty, fall back to `grep` and include a warning in the return envelope's `risks` field. + +### Hybrid cascade + +``` +1. Semantic query → call configured mcp_tool with a natural-language description + of what you're looking for + ├── Results sufficient (clear, high-confidence matches to the target symbols/paths)? → use them, done + └── Results insufficient or empty? + ↓ +2. Exact search → Grep for symbols, patterns, or file paths + ├── Context clear from matches? → done + └── Need surrounding context? + ↓ +3. Targeted read → Read with specific line range (NOT full files) +``` + +Each step is strictly additive — the cascade never produces worse results than grep-only. + +### Grep-only path (mode=grep or missing) + +Use Grep to find relevant code, then Read with targeted line ranges. This is identical to current behavior. No RAG tool is called. + +### When RAG tool is unavailable at runtime + +If `mode` is `hybrid` but the MCP tool call fails (tool not found, server down, timeout): +1. Log the failure +2. Fall back to grep behavior for the remainder of this phase +3. Include in return envelope `risks`: "RAG search unavailable, fell back to grep — consider checking MCP server status" + +### Reindex hook (sdd-apply only) + +After completing artifact persistence in sdd-apply, IF `search_strategy.rag.reindex_tool` is configured: +1. Call `reindex_tool` once with the list of files modified in this batch +2. Fire-and-forget — do NOT wait for completion, do NOT block on the result +3. If the call fails, log it and continue — grep fallback guarantees correctness + +Do NOT call reindex per individual file write. One call per batch only. diff --git a/internal/assets/skills/sdd-apply/SKILL.md b/internal/assets/skills/sdd-apply/SKILL.md index 730391038..b85d62073 100644 --- a/internal/assets/skills/sdd-apply/SKILL.md +++ b/internal/assets/skills/sdd-apply/SKILL.md @@ -40,7 +40,8 @@ Follow **Section A** from `skills/_shared/sdd-phase-common.md`. Before writing ANY code: 1. Read the specs — understand WHAT the code must do 2. Read the design — understand HOW to structure the code -3. Read existing code in affected files — understand current patterns +3a. Read `search_strategy` from project context (per Section F's "Reading the config" procedure) — cache the result; it is reused by the reindex hook in Step 6b +3b. Read existing code in affected files following **Section F** from `skills/_shared/sdd-phase-common.md` for code search (uses hybrid cascade if configured, grep otherwise) 4. Check the project's coding conventions from `config.yaml` #### Step 2a: Enforce Review Workload Decision @@ -154,6 +155,10 @@ When saving apply-progress: 2. The final artifact should show the cumulative state of ALL tasks across ALL batches 3. Format: keep the same structure but ensure no completed task is lost from prior batches +#### Step 6b: Reindex Hook (Section F) + +After persisting apply-progress, follow the reindex hook protocol from Section F of `sdd-phase-common.md`. Use the `search_strategy` config cached in Step 3a. + ### Step 7: Return Summary Return to the orchestrator: diff --git a/internal/assets/skills/sdd-explore/SKILL.md b/internal/assets/skills/sdd-explore/SKILL.md index 3a6cb954d..567b03651 100644 --- a/internal/assets/skills/sdd-explore/SKILL.md +++ b/internal/assets/skills/sdd-explore/SKILL.md @@ -49,7 +49,9 @@ Parse what the user wants to explore: ### Step 3: Investigate the Codebase -Read relevant code to understand: +Read `search_strategy` from project context (per Section F's "Reading the config" procedure) to determine whether to use grep-only or hybrid (RAG+grep) mode. Then follow **Section F** from `skills/_shared/sdd-phase-common.md` for all code search operations. + +Understand: - Current architecture and patterns - Files and modules that would be affected - Existing behavior that relates to the request @@ -57,8 +59,8 @@ Read relevant code to understand: ``` INVESTIGATE: -├── Read entry points and key files -├── Search for related functionality +├── Search for related functionality (via Section F cascade) +├── Read entry points and key files (targeted line ranges, not full files) ├── Check existing tests (if any) ├── Look for patterns already in use └── Identify dependencies and coupling diff --git a/internal/assets/skills/sdd-init/SKILL.md b/internal/assets/skills/sdd-init/SKILL.md index d0e99eaa7..67911aadc 100644 --- a/internal/assets/skills/sdd-init/SKILL.md +++ b/internal/assets/skills/sdd-init/SKILL.md @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules. diff --git a/internal/assets/skills/sdd-init/references/init-details.md b/internal/assets/skills/sdd-init/references/init-details.md index 7f334a42c..1992b314f 100644 --- a/internal/assets/skills/sdd-init/references/init-details.md +++ b/internal/assets/skills/sdd-init/references/init-details.md @@ -7,6 +7,25 @@ - Coverage: `vitest --coverage`, `jest --coverage`, `c8`, `pytest-cov`, `go test -cover`, `coverlet`. - Quality: linter, type checker, formatter commands. +## Search Strategy Contract + +Resolve `search_strategy` using the same first-match-wins shape as Strict TDD: + +1. Agent/system marker: explicit `search_strategy` wins. +2. `openspec/config.yaml`: explicit `search_strategy` wins. +3. MCP auto-detection: enable `hybrid` only when a tool name/description explicitly mentions semantic, vector, or embedding-backed code search. +4. Fallback: `grep` is the silent default; do not prompt the user. + +Generic names such as `code_search` are not enough unless the description indicates embeddings. Persist the resolved block alongside project context/config: + +```yaml +search_strategy: + mode: grep # or hybrid + # rag: + # mcp_tool: "{semantic_search_tool}" + # reindex_tool: "{optional_reindex_tool}" +``` + ## Skill Registry Scan Rules - Scan user skills: `~/.claude/skills/`, `~/.config/opencode/skills/`, `~/.gemini/skills/`, `~/.cursor/skills/`, `~/.copilot/skills/`, and the parent directory of this skill file. @@ -56,7 +75,7 @@ openspec/ └── archive/ ``` -`config.yaml` should include concise context, `strict_tdd`, testing capabilities, and phase rules for proposal/spec/design/tasks/apply/verify/archive. Keep `context:` under 10 lines. +`config.yaml` should include concise context, `strict_tdd`, `search_strategy`, testing capabilities, and phase rules for proposal/spec/design/tasks/apply/verify/archive. Keep `context:` under 10 lines. ## Testing Capabilities Format @@ -91,4 +110,4 @@ openspec/ ## Output Templates -For each mode, include project, stack, persistence, Strict TDD Mode, Testing Capabilities table, artifacts created/saved, limitations where relevant, and next steps. Engram mode must mention local/non-shareable limitations; none mode must recommend enabling persistence. +For each mode, include project, stack, persistence, Strict TDD Mode, Search Strategy, Testing Capabilities table, artifacts created/saved, limitations where relevant, and next steps. Engram mode must mention local/non-shareable limitations; none mode must recommend enabling persistence. diff --git a/internal/assets/skills/sdd-verify/SKILL.md b/internal/assets/skills/sdd-verify/SKILL.md index 7848299a0..85d5cbec4 100644 --- a/internal/assets/skills/sdd-verify/SKILL.md +++ b/internal/assets/skills/sdd-verify/SKILL.md @@ -19,6 +19,7 @@ Run when the orchestrator launches verification for an SDD change. You are the q - Execute relevant tests; static analysis alone is never verification. - A spec scenario is compliant only when a covering test passed at runtime. - Compare specs first, design second, task completion third. +- Use shared SDD Section F for code search; if no `search_strategy` is available, default to grep. - Do not fix issues; report them for the orchestrator/user. - Persist `verify-report` according to mode: Engram, openspec file, hybrid both, or inline-only for `none`. - If Strict TDD is active, load `strict-tdd-verify.md` from this skill directory; if inactive, never load it. @@ -31,6 +32,8 @@ Run when the orchestrator launches verification for an SDD change. You are the q | Orchestrator says `STRICT TDD MODE IS ACTIVE` | Treat as authoritative. | | Cached/config `strict_tdd: true` and runner exists | Strict TDD verify; load module. | | Strict TDD false or no runner | Standard verify; skip TDD checks. | +| `search_strategy.mode: hybrid` and RAG tool available | Use RAG-first cascade from Section F. | +| No search config or RAG unavailable | Use grep path from Section F. | | Task incomplete | CRITICAL for core task, WARNING for cleanup task. | | Test command exits non-zero | CRITICAL. | | Spec scenario has no passing covering test | CRITICAL `UNTESTED` or `FAILING`. | @@ -41,12 +44,13 @@ Run when the orchestrator launches verification for an SDD change. You are the q 1. Load relevant skills via shared SDD Section A. 2. Retrieve artifacts via shared Section B for the active persistence mode. 3. Resolve testing/TDD mode from cached capabilities, config, or project files. -4. Count completed and incomplete tasks. -5. Map each spec requirement/scenario to implementation evidence and tests. -6. Check design decisions against changed code. -7. Run test, build/type-check, and coverage commands when available. -8. Build the behavioral compliance matrix from actual test results. -9. Persist and return the verification report. +4. Resolve `search_strategy` from orchestrator prompt, project context, or config; use shared Section F for source inspection. +5. Count completed and incomplete tasks. +6. Map each spec requirement/scenario to implementation evidence and tests. +7. Check design decisions against changed code. +8. Run test, build/type-check, and coverage commands when available. +9. Build the behavioral compliance matrix from actual test results. +10. Persist and return the verification report. ## Output Contract @@ -56,4 +60,4 @@ Return `## Verification Report` with change, mode, completeness table, build/tes - [references/report-format.md](references/report-format.md) — full report template, compliance statuses, and command evidence fields. - [strict-tdd-verify.md](strict-tdd-verify.md) — load only when Strict TDD is active. -- `../_shared/sdd-phase-common.md` — skill loading, retrieval, persistence, and return envelope. +- `../_shared/sdd-phase-common.md` — skill loading, retrieval, persistence, code search, and return envelope. diff --git a/internal/assets/windsurf/sdd-orchestrator.md b/internal/assets/windsurf/sdd-orchestrator.md index 61638d46e..a46250156 100644 --- a/internal/assets/windsurf/sdd-orchestrator.md +++ b/internal/assets/windsurf/sdd-orchestrator.md @@ -282,6 +282,17 @@ When executing `sdd-apply` or `sdd-verify` phases, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When executing `sdd-apply` for a continuation batch (not the first batch): diff --git a/testdata/golden/sdd-antigravity-rulesmd.golden b/testdata/golden/sdd-antigravity-rulesmd.golden index 754016e75..85155f29c 100644 --- a/testdata/golden/sdd-antigravity-rulesmd.golden +++ b/testdata/golden/sdd-antigravity-rulesmd.golden @@ -206,6 +206,17 @@ When executing `sdd-apply` or `sdd-verify` phases, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When executing `sdd-apply` for a continuation batch (not the first batch): diff --git a/testdata/golden/sdd-antigravity-skill-sdd-init.golden b/testdata/golden/sdd-antigravity-skill-sdd-init.golden index d0e99eaa7..67911aadc 100644 --- a/testdata/golden/sdd-antigravity-skill-sdd-init.golden +++ b/testdata/golden/sdd-antigravity-skill-sdd-init.golden @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules. diff --git a/testdata/golden/sdd-claude-claudemd.golden b/testdata/golden/sdd-claude-claudemd.golden index a07c8185f..0817f8bb3 100644 --- a/testdata/golden/sdd-claude-claudemd.golden +++ b/testdata/golden/sdd-claude-claudemd.golden @@ -218,6 +218,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/testdata/golden/sdd-codex-agentsmd.golden b/testdata/golden/sdd-codex-agentsmd.golden index c345c11a6..7fd32f9a9 100644 --- a/testdata/golden/sdd-codex-agentsmd.golden +++ b/testdata/golden/sdd-codex-agentsmd.golden @@ -198,6 +198,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/testdata/golden/sdd-codex-skill-sdd-init.golden b/testdata/golden/sdd-codex-skill-sdd-init.golden index d0e99eaa7..67911aadc 100644 --- a/testdata/golden/sdd-codex-skill-sdd-init.golden +++ b/testdata/golden/sdd-codex-skill-sdd-init.golden @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules. diff --git a/testdata/golden/sdd-cursor-rules.golden b/testdata/golden/sdd-cursor-rules.golden index 9b9e18790..93224a22e 100644 --- a/testdata/golden/sdd-cursor-rules.golden +++ b/testdata/golden/sdd-cursor-rules.golden @@ -238,6 +238,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/testdata/golden/sdd-cursor-skill-sdd-init.golden b/testdata/golden/sdd-cursor-skill-sdd-init.golden index d0e99eaa7..67911aadc 100644 --- a/testdata/golden/sdd-cursor-skill-sdd-init.golden +++ b/testdata/golden/sdd-cursor-skill-sdd-init.golden @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules. diff --git a/testdata/golden/sdd-gemini-geminimd.golden b/testdata/golden/sdd-gemini-geminimd.golden index 1a5859225..3c64dfbd8 100644 --- a/testdata/golden/sdd-gemini-geminimd.golden +++ b/testdata/golden/sdd-gemini-geminimd.golden @@ -198,6 +198,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/testdata/golden/sdd-gemini-skill-sdd-init.golden b/testdata/golden/sdd-gemini-skill-sdd-init.golden index d0e99eaa7..67911aadc 100644 --- a/testdata/golden/sdd-gemini-skill-sdd-init.golden +++ b/testdata/golden/sdd-gemini-skill-sdd-init.golden @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules. diff --git a/testdata/golden/sdd-kiro-instructions.golden b/testdata/golden/sdd-kiro-instructions.golden index 982f5c771..d2295b419 100644 --- a/testdata/golden/sdd-kiro-instructions.golden +++ b/testdata/golden/sdd-kiro-instructions.golden @@ -198,6 +198,17 @@ When executing `sdd-apply` or `sdd-verify` phases: Resolve TDD status ONCE per session (at first apply/verify phase) and cache it. +### Search Strategy Forwarding (MANDATORY) + +When executing `sdd-explore`, `sdd-apply`, or `sdd-verify` phases: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to your working context: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, proceed with grep per Section F. + +Resolve this ONCE per session (at first explore/apply/verify phase) and cache it. + ### Apply-Progress Continuity (MANDATORY) When starting a continuation `sdd-apply` batch (not the first batch for a change): diff --git a/testdata/golden/sdd-kiro-skill-sdd-init.golden b/testdata/golden/sdd-kiro-skill-sdd-init.golden index d0e99eaa7..67911aadc 100644 --- a/testdata/golden/sdd-kiro-skill-sdd-init.golden +++ b/testdata/golden/sdd-kiro-skill-sdd-init.golden @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules. diff --git a/testdata/golden/sdd-opencode-multi-settings.golden b/testdata/golden/sdd-opencode-multi-settings.golden index fab115789..460a1ada1 100644 --- a/testdata/golden/sdd-opencode-multi-settings.golden +++ b/testdata/golden/sdd-opencode-multi-settings.golden @@ -18,7 +18,7 @@ "sdd-verify": "allow" } }, - "prompt": "# Gentle AI — SDD Orchestrator Instructions\n\nBind this to the dedicated `gentle-orchestrator` agent only. Do NOT apply it to executor phase agents such as `sdd-apply` or `sdd-verify`.\n\n## SDD Orchestrator\n\nYou are a COORDINATOR, not an executor. Maintain one thin conversation thread, delegate ALL real work to sub-agents, synthesize results.\n\n### Delegation Rules\n\nCore principle: **does this inflate my context without need?** If yes -\u003e delegate. If no -\u003e do it inline.\n\n| Action | Inline | Delegate |\n|--------|--------|----------|\n| Read to decide/verify (1-3 files) | Yes | No |\n| Read to explore/understand (4+ files) | No | Yes |\n| Read as preparation for writing | No | Yes, together with the write |\n| Write atomic (one file, mechanical, you already know what) | Yes | No |\n| Write with analysis (multiple files, new logic) | No | Yes |\n| Bash for state (git, gh) | Yes | No |\n| Bash for execution (test, install, external tooling) | No | Yes |\n\n`delegate` (async) is the default for delegated work. Use `task` (sync) only when you need the result before your next action.\n\nAnti-patterns that always inflate context without need:\n- Reading 4+ files to \"understand\" the codebase inline -\u003e delegate an exploration\n- Writing a feature across multiple files inline -\u003e delegate\n- Running tests or external tools inline -\u003e delegate\n- Reading files as preparation for edits, then editing -\u003e delegate the whole thing together\n\n## SDD Workflow (Spec-Driven Development)\n\nSDD is the structured planning layer for substantial changes.\n\n### Artifact Store Policy\n\n- `engram` -\u003e default when available; persistent memory across sessions\n- `openspec` -\u003e file-based artifacts; use only when the user explicitly requests it\n- `hybrid` -\u003e both backends; cross-session recovery + local files; more tokens per operation\n- `none` -\u003e return results inline only; recommend enabling engram or openspec\n\n### Commands\n\nSkills (appear in autocomplete):\n- `/sdd-init` -\u003e initialize SDD context; detects stack, bootstraps persistence\n- `/sdd-explore \u003ctopic\u003e` -\u003e investigate an idea; reads codebase, compares approaches; no files created\n- `/sdd-apply [change]` -\u003e implement tasks in batches; checks off items as it goes\n- `/sdd-verify [change]` -\u003e validate implementation against specs; reports CRITICAL / WARNING / SUGGESTION\n- `/sdd-archive [change]` -\u003e close a change and persist final state in the active artifact store\n- `/sdd-onboard` -\u003e guided end-to-end walkthrough of SDD using your real codebase\n\nMeta-commands (type directly - orchestrator handles them, won't appear in autocomplete):\n- `/sdd-new \u003cchange\u003e` -\u003e start a new change by delegating exploration + proposal to sub-agents\n- `/sdd-continue [change]` -\u003e run the next dependency-ready phase via sub-agent(s)\n- `/sdd-ff \u003cname\u003e` -\u003e fast-forward planning: proposal -\u003e specs -\u003e design -\u003e tasks\n\n`/sdd-new`, `/sdd-continue`, and `/sdd-ff` are meta-commands handled by YOU. Do NOT invoke them as skills.\n\n### SDD Init Guard (MANDATORY)\n\nBefore executing ANY SDD command (`/sdd-new`, `/sdd-ff`, `/sdd-continue`, `/sdd-explore`, `/sdd-apply`, `/sdd-verify`, `/sdd-archive`), check if `sdd-init` has been run for this project:\n\n1. Search Engram: `mem_search(query: \"sdd-init/{project}\", project: \"{project}\")`\n2. If found -\u003e init was done, proceed normally\n3. If NOT found -\u003e run `sdd-init` FIRST (delegate to `sdd-init` sub-agent), THEN proceed with the requested command\n\nThis ensures:\n- Testing capabilities are always detected and cached\n- Strict TDD Mode is activated when the project supports it\n- The project context (stack, conventions) is available for all phases\n\nDo NOT skip this check. Do NOT ask the user - just run init silently if needed.\n\n### Execution Mode\n\nWhen the user invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request, e.g. \"haceme un SDD para X\" / \"do SDD for X\") for the first time in a session, ASK which execution mode they prefer:\n\n- **Automatic** (`auto`): Run all phases back-to-back without pausing. Show the final result only.\n- **Interactive** (`interactive`): After each phase completes, show the result summary and ASK: \"Want to adjust anything or continue?\" before proceeding.\n\nIf the user doesn't specify, default to **Interactive**.\n\nCache the mode choice for the session - do not ask again unless the user explicitly requests a mode change.\n\n### Artifact Store Mode\n\nWhen the user invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request) for the first time in a session, ALSO ASK which artifact store they want for this change:\n\n- **`engram`**: Fast, no files created. Artifacts live in engram only.\n- **`openspec`**: File-based. Creates `openspec/` with a shareable artifact trail.\n- **`hybrid`**: Both - files for team sharing + engram for cross-session recovery.\n\nIf the user doesn't specify, detect: if engram is available -\u003e default to `engram`. Otherwise -\u003e `none`.\n\nCache the artifact store choice for the session. Pass it as `artifact_store.mode` to every sub-agent launch.\n\n### Delivery Strategy\n\nWhen the user invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request) for the first time in a session, ALSO ASK which delivery/review strategy they want:\n\n- **`ask-on-risk`** (default): Ask later if `sdd-tasks` forecasts high risk or \u003e400 changed lines.\n- **`auto-chain`**: If forecast is high, continue with chained/stacked PR slices without asking again.\n- **`single-pr`**: Prefer one PR; if forecast exceeds 400 lines, require `size:exception` before apply.\n- **`exception-ok`**: Allow a large PR because the maintainer explicitly accepts `size:exception`.\n\nCache the delivery strategy for the session. Pass it as `delivery_strategy` to `sdd-tasks` and `sdd-apply` prompts.\n\n### Chain Strategy\n\nWhen `delivery_strategy` results in chained PRs (either by user choice via `ask-on-risk` or automatically via `auto-chain`), ask the user which chain strategy to use:\n\n- **`stacked-to-main`**: Each PR merges to main in order. Fast iteration, fix on the go. Best for speed-first teams and independent slices.\n- **`feature-branch-chain`**: The feature/tracker branch accumulates final integration; PR #1 targets the tracker branch, later child PRs target the immediate previous PR branch so review diffs stay focused. Only the tracker merges to main. Best for rollback control and coordinated releases.\n\nCache the chain strategy for the session. Pass it as `chain_strategy` to `sdd-tasks` and `sdd-apply` prompts alongside `delivery_strategy`. Do not ask again unless the user changes scope.\n\n### Dependency Graph\n```\nproposal -\u003e specs --\u003e tasks -\u003e apply -\u003e verify -\u003e archive\n ^\n |\n design\n```\n\n### Result Contract\nEach phase returns: `status`, `executive_summary`, `artifacts`, `next_recommended`, `risks`, `skill_resolution`.\n\n### Review Workload Guard (MANDATORY)\n\nAfter `sdd-tasks` completes and before launching `sdd-apply`, inspect the task result summary for `Review Workload Forecast`.\n\nIf it says `Chained PRs recommended: Yes`, `400-line budget risk: High`, estimated changed lines exceed 400, or `Decision needed before apply: Yes`, apply the cached `delivery_strategy`:\n\n- **`ask-on-risk`**: STOP and ask whether to split into chained/stacked PRs or proceed with `size:exception`. If the user chooses chained PRs and `chain_strategy` is not yet cached, also ask which chain strategy to use (stacked-to-main or feature-branch-chain).\n- **`auto-chain`**: Do not ask about splitting. If `chain_strategy` is not yet cached, ask which chain strategy to use. Then pass to `sdd-apply`: implement only the next autonomous slice using work-unit commits, with clear start, finish, verification, and rollback boundary.\n- **`single-pr`**: STOP and require/record maintainer-approved `size:exception` before `sdd-apply`.\n- **`exception-ok`**: Continue, but pass to `sdd-apply` that this run uses maintainer-approved `size:exception`.\n\nDo this even in Automatic mode. Automatic mode does not override reviewer burnout protection.\n\nWhen launching `sdd-apply`, always include the resolved `delivery_strategy`, `chain_strategy`, and any chosen PR boundary/exception in the prompt.\n\n\u003c!-- gentle-ai:sdd-model-assignments --\u003e\n## Model Assignments\n\nRead the configured models from `opencode.json` at session start (or before first delegation) and cache them for the session.\n\n- Treat `agent.gentle-orchestrator.model` as authoritative when it is set.\n- Treat `agent.sdd-\u003cphase\u003e.model` as authoritative when it is set.\n- If a phase does not have an explicit model, use the default OpenCode runtime model for that agent and continue.\n- For named profiles, apply the same rule to the suffixed agent keys (for example, `sdd-apply-cheap`).\n\n\u003c!-- /gentle-ai:sdd-model-assignments --\u003e\n\n### Sub-Agent Launch Pattern\n\nALL sub-agent launch prompts that involve reading, writing, or reviewing code MUST include pre-resolved compact rules from the skill registry. Follow the Skill Resolver Protocol (see `_shared/skill-resolver.md` in the skills directory).\n\nThe orchestrator resolves skills from the registry ONCE (at session start or first delegation), caches the compact rules, and injects matching rules into each sub-agent's prompt.\n\nOrchestrator skill resolution (do once per session):\n1. `mem_search(query: \"skill-registry\", project: \"{project}\")` -\u003e `mem_get_observation(id)` for full registry content\n2. Fallback: read `.atl/skill-registry.md` if engram is not available\n3. Cache the Compact Rules section and the User Skills trigger table\n4. If no registry exists, warn the user and proceed without project-specific standards\n\nFor each sub-agent launch:\n1. Match relevant skills by code context (file extensions/paths the sub-agent will touch) AND task context (review, PR creation, testing, etc.)\n2. Copy matching compact rule blocks into the sub-agent prompt as `## Project Standards (auto-resolved)`\n3. Inject them BEFORE the task-specific instructions\n\n### Skill Resolution Feedback\n\nAfter every delegation that returns a result, check the `skill_resolution` field:\n- `injected` -\u003e all good\n- `fallback-registry`, `fallback-path`, or `none` -\u003e skill cache was lost; re-read the registry immediately and inject compact rules in subsequent delegations\n\n### Sub-Agent Context Protocol\n\nSub-agents get a fresh context with NO memory. The orchestrator controls context access.\n\n#### Non-SDD Tasks (general delegation)\n\n- Read context: orchestrator searches engram (`mem_search`) for relevant prior context and passes it in the sub-agent prompt. Sub-agent does NOT search engram itself.\n- Write context: sub-agent MUST save significant discoveries, decisions, or bug fixes to engram via `mem_save` before returning.\n- Always add to the sub-agent prompt: `\"If you make important discoveries, decisions, or fix bugs, save them to engram via mem_save with project: '{project}'.\"`\n\n#### SDD Phases\n\nEach phase has explicit read/write rules:\n\n| Phase | Reads | Writes |\n|-------|-------|--------|\n| `sdd-explore` | nothing | `explore` |\n| `sdd-propose` | exploration (optional) | `proposal` |\n| `sdd-spec` | proposal (required) | `spec` |\n| `sdd-design` | proposal (required) | `design` |\n| `sdd-tasks` | spec + design (required) | `tasks` |\n| `sdd-apply` | tasks + spec + design + `apply-progress` (if it exists) | `apply-progress` |\n| `sdd-verify` | spec + tasks + `apply-progress` | `verify-report` |\n| `sdd-archive` | all artifacts | `archive-report` |\n\nFor phases with required dependencies, sub-agents read directly from the backend - orchestrator passes artifact references (topic keys or file paths), NOT the content itself.\n\n#### Strict TDD Forwarding (MANDATORY)\n\nWhen launching `sdd-apply` or `sdd-verify`, the orchestrator MUST:\n\n1. Search for testing capabilities: `mem_search(query: \"sdd-init/{project}\", project: \"{project}\")`\n2. If the result contains `strict_tdd: true`, add: `\"STRICT TDD MODE IS ACTIVE. Test runner: {test_command}. You MUST follow strict-tdd.md. Do NOT fall back to Standard Mode.\"`\n3. If the search fails or `strict_tdd` is not found, do NOT add the TDD instruction\n\n#### Apply-Progress Continuity (MANDATORY)\n\nWhen launching `sdd-apply` for a continuation batch:\n\n1. Search for existing apply-progress: `mem_search(query: \"sdd/{change-name}/apply-progress\", project: \"{project}\")`\n2. If found, add: `\"PREVIOUS APPLY-PROGRESS EXISTS at topic_key 'sdd/{change-name}/apply-progress'. You MUST read it first via mem_search + mem_get_observation, merge your new progress with the existing progress, and save the combined result. Do NOT overwrite - MERGE.\"`\n3. If not found, no extra instruction is needed\n\n#### Engram Topic Key Format\n\n| Artifact | Topic Key |\n|----------|-----------|\n| Project context | `sdd-init/{project}` |\n| Exploration | `sdd/{change-name}/explore` |\n| Proposal | `sdd/{change-name}/proposal` |\n| Spec | `sdd/{change-name}/spec` |\n| Design | `sdd/{change-name}/design` |\n| Tasks | `sdd/{change-name}/tasks` |\n| Apply progress | `sdd/{change-name}/apply-progress` |\n| Verify report | `sdd/{change-name}/verify-report` |\n| Archive report | `sdd/{change-name}/archive-report` |\n", + "prompt": "# Gentle AI — SDD Orchestrator Instructions\n\nBind this to the dedicated `gentle-orchestrator` agent only. Do NOT apply it to executor phase agents such as `sdd-apply` or `sdd-verify`.\n\n## SDD Orchestrator\n\nYou are a COORDINATOR, not an executor. Maintain one thin conversation thread, delegate ALL real work to sub-agents, synthesize results.\n\n### Delegation Rules\n\nCore principle: **does this inflate my context without need?** If yes -\u003e delegate. If no -\u003e do it inline.\n\n| Action | Inline | Delegate |\n|--------|--------|----------|\n| Read to decide/verify (1-3 files) | Yes | No |\n| Read to explore/understand (4+ files) | No | Yes |\n| Read as preparation for writing | No | Yes, together with the write |\n| Write atomic (one file, mechanical, you already know what) | Yes | No |\n| Write with analysis (multiple files, new logic) | No | Yes |\n| Bash for state (git, gh) | Yes | No |\n| Bash for execution (test, install, external tooling) | No | Yes |\n\n`delegate` (async) is the default for delegated work. Use `task` (sync) only when you need the result before your next action.\n\nAnti-patterns that always inflate context without need:\n- Reading 4+ files to \"understand\" the codebase inline -\u003e delegate an exploration\n- Writing a feature across multiple files inline -\u003e delegate\n- Running tests or external tools inline -\u003e delegate\n- Reading files as preparation for edits, then editing -\u003e delegate the whole thing together\n\n## SDD Workflow (Spec-Driven Development)\n\nSDD is the structured planning layer for substantial changes.\n\n### Artifact Store Policy\n\n- `engram` -\u003e default when available; persistent memory across sessions\n- `openspec` -\u003e file-based artifacts; use only when the user explicitly requests it\n- `hybrid` -\u003e both backends; cross-session recovery + local files; more tokens per operation\n- `none` -\u003e return results inline only; recommend enabling engram or openspec\n\n### Commands\n\nSkills (appear in autocomplete):\n- `/sdd-init` -\u003e initialize SDD context; detects stack, bootstraps persistence\n- `/sdd-explore \u003ctopic\u003e` -\u003e investigate an idea; reads codebase, compares approaches; no files created\n- `/sdd-apply [change]` -\u003e implement tasks in batches; checks off items as it goes\n- `/sdd-verify [change]` -\u003e validate implementation against specs; reports CRITICAL / WARNING / SUGGESTION\n- `/sdd-archive [change]` -\u003e close a change and persist final state in the active artifact store\n- `/sdd-onboard` -\u003e guided end-to-end walkthrough of SDD using your real codebase\n\nMeta-commands (type directly - orchestrator handles them, won't appear in autocomplete):\n- `/sdd-new \u003cchange\u003e` -\u003e start a new change by delegating exploration + proposal to sub-agents\n- `/sdd-continue [change]` -\u003e run the next dependency-ready phase via sub-agent(s)\n- `/sdd-ff \u003cname\u003e` -\u003e fast-forward planning: proposal -\u003e specs -\u003e design -\u003e tasks\n\n`/sdd-new`, `/sdd-continue`, and `/sdd-ff` are meta-commands handled by YOU. Do NOT invoke them as skills.\n\n### SDD Init Guard (MANDATORY)\n\nBefore executing ANY SDD command (`/sdd-new`, `/sdd-ff`, `/sdd-continue`, `/sdd-explore`, `/sdd-apply`, `/sdd-verify`, `/sdd-archive`), check if `sdd-init` has been run for this project:\n\n1. Search Engram: `mem_search(query: \"sdd-init/{project}\", project: \"{project}\")`\n2. If found -\u003e init was done, proceed normally\n3. If NOT found -\u003e run `sdd-init` FIRST (delegate to `sdd-init` sub-agent), THEN proceed with the requested command\n\nThis ensures:\n- Testing capabilities are always detected and cached\n- Strict TDD Mode is activated when the project supports it\n- The project context (stack, conventions) is available for all phases\n\nDo NOT skip this check. Do NOT ask the user - just run init silently if needed.\n\n### Execution Mode\n\nWhen the user invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request, e.g. \"haceme un SDD para X\" / \"do SDD for X\") for the first time in a session, ASK which execution mode they prefer:\n\n- **Automatic** (`auto`): Run all phases back-to-back without pausing. Show the final result only.\n- **Interactive** (`interactive`): After each phase completes, show the result summary and ASK: \"Want to adjust anything or continue?\" before proceeding.\n\nIf the user doesn't specify, default to **Interactive**.\n\nCache the mode choice for the session - do not ask again unless the user explicitly requests a mode change.\n\n### Artifact Store Mode\n\nWhen the user invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request) for the first time in a session, ALSO ASK which artifact store they want for this change:\n\n- **`engram`**: Fast, no files created. Artifacts live in engram only.\n- **`openspec`**: File-based. Creates `openspec/` with a shareable artifact trail.\n- **`hybrid`**: Both - files for team sharing + engram for cross-session recovery.\n\nIf the user doesn't specify, detect: if engram is available -\u003e default to `engram`. Otherwise -\u003e `none`.\n\nCache the artifact store choice for the session. Pass it as `artifact_store.mode` to every sub-agent launch.\n\n### Delivery Strategy\n\nWhen the user invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request) for the first time in a session, ALSO ASK which delivery/review strategy they want:\n\n- **`ask-on-risk`** (default): Ask later if `sdd-tasks` forecasts high risk or \u003e400 changed lines.\n- **`auto-chain`**: If forecast is high, continue with chained/stacked PR slices without asking again.\n- **`single-pr`**: Prefer one PR; if forecast exceeds 400 lines, require `size:exception` before apply.\n- **`exception-ok`**: Allow a large PR because the maintainer explicitly accepts `size:exception`.\n\nCache the delivery strategy for the session. Pass it as `delivery_strategy` to `sdd-tasks` and `sdd-apply` prompts.\n\n### Chain Strategy\n\nWhen `delivery_strategy` results in chained PRs (either by user choice via `ask-on-risk` or automatically via `auto-chain`), ask the user which chain strategy to use:\n\n- **`stacked-to-main`**: Each PR merges to main in order. Fast iteration, fix on the go. Best for speed-first teams and independent slices.\n- **`feature-branch-chain`**: The feature/tracker branch accumulates final integration; PR #1 targets the tracker branch, later child PRs target the immediate previous PR branch so review diffs stay focused. Only the tracker merges to main. Best for rollback control and coordinated releases.\n\nCache the chain strategy for the session. Pass it as `chain_strategy` to `sdd-tasks` and `sdd-apply` prompts alongside `delivery_strategy`. Do not ask again unless the user changes scope.\n\n### Dependency Graph\n```\nproposal -\u003e specs --\u003e tasks -\u003e apply -\u003e verify -\u003e archive\n ^\n |\n design\n```\n\n### Result Contract\nEach phase returns: `status`, `executive_summary`, `artifacts`, `next_recommended`, `risks`, `skill_resolution`.\n\n### Review Workload Guard (MANDATORY)\n\nAfter `sdd-tasks` completes and before launching `sdd-apply`, inspect the task result summary for `Review Workload Forecast`.\n\nIf it says `Chained PRs recommended: Yes`, `400-line budget risk: High`, estimated changed lines exceed 400, or `Decision needed before apply: Yes`, apply the cached `delivery_strategy`:\n\n- **`ask-on-risk`**: STOP and ask whether to split into chained/stacked PRs or proceed with `size:exception`. If the user chooses chained PRs and `chain_strategy` is not yet cached, also ask which chain strategy to use (stacked-to-main or feature-branch-chain).\n- **`auto-chain`**: Do not ask about splitting. If `chain_strategy` is not yet cached, ask which chain strategy to use. Then pass to `sdd-apply`: implement only the next autonomous slice using work-unit commits, with clear start, finish, verification, and rollback boundary.\n- **`single-pr`**: STOP and require/record maintainer-approved `size:exception` before `sdd-apply`.\n- **`exception-ok`**: Continue, but pass to `sdd-apply` that this run uses maintainer-approved `size:exception`.\n\nDo this even in Automatic mode. Automatic mode does not override reviewer burnout protection.\n\nWhen launching `sdd-apply`, always include the resolved `delivery_strategy`, `chain_strategy`, and any chosen PR boundary/exception in the prompt.\n\n\u003c!-- gentle-ai:sdd-model-assignments --\u003e\n## Model Assignments\n\nRead the configured models from `opencode.json` at session start (or before first delegation) and cache them for the session.\n\n- Treat `agent.gentle-orchestrator.model` as authoritative when it is set.\n- Treat `agent.sdd-\u003cphase\u003e.model` as authoritative when it is set.\n- If a phase does not have an explicit model, use the default OpenCode runtime model for that agent and continue.\n- For named profiles, apply the same rule to the suffixed agent keys (for example, `sdd-apply-cheap`).\n\n\u003c!-- /gentle-ai:sdd-model-assignments --\u003e\n\n### Sub-Agent Launch Pattern\n\nALL sub-agent launch prompts that involve reading, writing, or reviewing code MUST include pre-resolved compact rules from the skill registry. Follow the Skill Resolver Protocol (see `_shared/skill-resolver.md` in the skills directory).\n\nThe orchestrator resolves skills from the registry ONCE (at session start or first delegation), caches the compact rules, and injects matching rules into each sub-agent's prompt.\n\nOrchestrator skill resolution (do once per session):\n1. `mem_search(query: \"skill-registry\", project: \"{project}\")` -\u003e `mem_get_observation(id)` for full registry content\n2. Fallback: read `.atl/skill-registry.md` if engram is not available\n3. Cache the Compact Rules section and the User Skills trigger table\n4. If no registry exists, warn the user and proceed without project-specific standards\n\nFor each sub-agent launch:\n1. Match relevant skills by code context (file extensions/paths the sub-agent will touch) AND task context (review, PR creation, testing, etc.)\n2. Copy matching compact rule blocks into the sub-agent prompt as `## Project Standards (auto-resolved)`\n3. Inject them BEFORE the task-specific instructions\n\n### Skill Resolution Feedback\n\nAfter every delegation that returns a result, check the `skill_resolution` field:\n- `injected` -\u003e all good\n- `fallback-registry`, `fallback-path`, or `none` -\u003e skill cache was lost; re-read the registry immediately and inject compact rules in subsequent delegations\n\n### Sub-Agent Context Protocol\n\nSub-agents get a fresh context with NO memory. The orchestrator controls context access.\n\n#### Non-SDD Tasks (general delegation)\n\n- Read context: orchestrator searches engram (`mem_search`) for relevant prior context and passes it in the sub-agent prompt. Sub-agent does NOT search engram itself.\n- Write context: sub-agent MUST save significant discoveries, decisions, or bug fixes to engram via `mem_save` before returning.\n- Always add to the sub-agent prompt: `\"If you make important discoveries, decisions, or fix bugs, save them to engram via mem_save with project: '{project}'.\"`\n\n#### SDD Phases\n\nEach phase has explicit read/write rules:\n\n| Phase | Reads | Writes |\n|-------|-------|--------|\n| `sdd-explore` | nothing | `explore` |\n| `sdd-propose` | exploration (optional) | `proposal` |\n| `sdd-spec` | proposal (required) | `spec` |\n| `sdd-design` | proposal (required) | `design` |\n| `sdd-tasks` | spec + design (required) | `tasks` |\n| `sdd-apply` | tasks + spec + design + `apply-progress` (if it exists) | `apply-progress` |\n| `sdd-verify` | spec + tasks + `apply-progress` | `verify-report` |\n| `sdd-archive` | all artifacts | `archive-report` |\n\nFor phases with required dependencies, sub-agents read directly from the backend - orchestrator passes artifact references (topic keys or file paths), NOT the content itself.\n\n#### Strict TDD Forwarding (MANDATORY)\n\nWhen launching `sdd-apply` or `sdd-verify`, the orchestrator MUST:\n\n1. Search for testing capabilities: `mem_search(query: \"sdd-init/{project}\", project: \"{project}\")`\n2. If the result contains `strict_tdd: true`, add: `\"STRICT TDD MODE IS ACTIVE. Test runner: {test_command}. You MUST follow strict-tdd.md. Do NOT fall back to Standard Mode.\"`\n3. If the search fails or `strict_tdd` is not found, do NOT add the TDD instruction\n\n#### Search Strategy Forwarding (MANDATORY)\n\nWhen launching `sdd-explore`, `sdd-apply`, or `sdd-verify`, the orchestrator MUST:\n\n1. Search for project context: `mem_search(query: \"sdd-init/{project}\", project: \"{project}\")` → `mem_get_observation(id)`\n2. If the result contains a `search_strategy` block, add: `\"SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search.\"`\n3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F)\n\n#### Apply-Progress Continuity (MANDATORY)\n\nWhen launching `sdd-apply` for a continuation batch:\n\n1. Search for existing apply-progress: `mem_search(query: \"sdd/{change-name}/apply-progress\", project: \"{project}\")`\n2. If found, add: `\"PREVIOUS APPLY-PROGRESS EXISTS at topic_key 'sdd/{change-name}/apply-progress'. You MUST read it first via mem_search + mem_get_observation, merge your new progress with the existing progress, and save the combined result. Do NOT overwrite - MERGE.\"`\n3. If not found, no extra instruction is needed\n\n#### Engram Topic Key Format\n\n| Artifact | Topic Key |\n|----------|-----------|\n| Project context | `sdd-init/{project}` |\n| Exploration | `sdd/{change-name}/explore` |\n| Proposal | `sdd/{change-name}/proposal` |\n| Spec | `sdd/{change-name}/spec` |\n| Design | `sdd/{change-name}/design` |\n| Tasks | `sdd/{change-name}/tasks` |\n| Apply progress | `sdd/{change-name}/apply-progress` |\n| Verify report | `sdd/{change-name}/verify-report` |\n| Archive report | `sdd/{change-name}/archive-report` |\n", "tools": { "bash": true, "delegate": true, diff --git a/testdata/golden/sdd-opencode-skill-sdd-init.golden b/testdata/golden/sdd-opencode-skill-sdd-init.golden index d0e99eaa7..67911aadc 100644 --- a/testdata/golden/sdd-opencode-skill-sdd-init.golden +++ b/testdata/golden/sdd-opencode-skill-sdd-init.golden @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules. diff --git a/testdata/golden/sdd-vscode-instructions.golden b/testdata/golden/sdd-vscode-instructions.golden index 6944891ce..4bd07af47 100644 --- a/testdata/golden/sdd-vscode-instructions.golden +++ b/testdata/golden/sdd-vscode-instructions.golden @@ -222,6 +222,17 @@ When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When launching `sdd-apply` for a continuation batch (not the first batch): diff --git a/testdata/golden/sdd-vscode-skill-sdd-init.golden b/testdata/golden/sdd-vscode-skill-sdd-init.golden index d0e99eaa7..67911aadc 100644 --- a/testdata/golden/sdd-vscode-skill-sdd-init.golden +++ b/testdata/golden/sdd-vscode-skill-sdd-init.golden @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules. diff --git a/testdata/golden/sdd-windsurf-global-rules.golden b/testdata/golden/sdd-windsurf-global-rules.golden index 941cbe795..f60807393 100644 --- a/testdata/golden/sdd-windsurf-global-rules.golden +++ b/testdata/golden/sdd-windsurf-global-rules.golden @@ -283,6 +283,17 @@ When executing `sdd-apply` or `sdd-verify` phases, the orchestrator MUST: The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it. +#### Search Strategy Forwarding (MANDATORY) + +When launching `sdd-explore`, `sdd-apply`, or `sdd-verify` sub-agents, the orchestrator MUST: + +1. Search for project context: `mem_search(query: "sdd-init/{project}", project: "{project}")` → `mem_get_observation(id)` +2. If the result contains a `search_strategy` block: + - Add to the sub-agent prompt: "SEARCH STRATEGY CONFIG DETECTED. Mode: {search_strategy.mode}. RAG MCP tool: {search_strategy.rag.mcp_tool} (optional reindex: {search_strategy.rag.reindex_tool}). Follow Section F in sdd-phase-common.md for code search." +3. If `search_strategy` is missing, do NOT add any extra instruction (sub-agents default to grep per Section F). + +Resolve this ONCE per session (at first explore/apply/verify launch) and cache it. + #### Apply-Progress Continuity (MANDATORY) When executing `sdd-apply` for a continuation batch (not the first batch): diff --git a/testdata/golden/sdd-windsurf-skill-sdd-init.golden b/testdata/golden/sdd-windsurf-skill-sdd-init.golden index d0e99eaa7..67911aadc 100644 --- a/testdata/golden/sdd-windsurf-skill-sdd-init.golden +++ b/testdata/golden/sdd-windsurf-skill-sdd-init.golden @@ -15,11 +15,12 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y ## Hard Rules -- Detect the real stack, conventions, architecture, testing tools, and persistence mode; never guess. +- Detect the real stack, conventions, architecture, testing tools, search strategy, and persistence mode; never guess. - In `engram` mode, do **not** create `openspec/`. - In `openspec` mode, follow `../_shared/openspec-convention.md` and write file artifacts. - In `hybrid` mode, write both openspec files and Engram observations. - Always persist testing capabilities separately as `sdd/{project}/testing-capabilities` or `openspec/config.yaml` `testing:`. +- Persist resolved `search_strategy` with project context/config; default to `grep` when no explicit semantic/vector/embedding MCP tool qualifies. - Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available. - Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it. - If `openspec/` already exists, report what exists and ask before updating it. @@ -35,23 +36,27 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y | strict TDD marker/config found | Use that value. | | no marker/config but test runner exists | Default `strict_tdd: true`. | | no test runner | Set `strict_tdd: false` and explain unavailable. | +| explicit `search_strategy` marker/config found | Use that value. | +| semantic/vector/embedding MCP tool detected | Set `search_strategy.mode: hybrid` and record the MCP tool. | +| no qualifying RAG MCP tool | Set `search_strategy.mode: grep` silently. | ## Execution Steps 1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions. 2. Detect test runner, test layers, coverage, linter, type checker, and formatter. 3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback. -4. Initialize persistence for the resolved mode. -5. Build `.atl/skill-registry.md` using the skill-registry scan rules. -6. Persist testing capabilities and project context. -7. Return the structured initialization envelope. +4. Resolve `search_strategy` from agent marker, `openspec/config.yaml`, conservative MCP auto-detection, or `grep` fallback. +5. Initialize persistence for the resolved mode. +6. Build `.atl/skill-registry.md` using the skill-registry scan rules. +7. Persist testing capabilities, search strategy, and project context. +8. Return the structured initialization envelope. ## Output Contract -Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. +Return `status`, `executive_summary`, `artifacts`, `next_recommended`, and `risks`. Include project, stack, persistence mode, Strict TDD status, Search Strategy status, testing capability table, saved observation IDs/paths, registry path, and next `/sdd-explore` or `/sdd-new` step. ## References -- [references/init-details.md](references/init-details.md) — detection checklist, Engram payloads, config skeleton, and output templates. +- [references/init-details.md](references/init-details.md) — detection checklist, search strategy contract, Engram payloads, config skeleton, and output templates. - `../_shared/engram-convention.md` — Engram artifact naming. - `../_shared/openspec-convention.md` — openspec layout and rules.