opensddrag 0.1.2 → 0.2.2

package/src/templates/skills/index.js

@@ -1,387 +1,72 @@
-export function getOpenCodeSkills(slug, _serverUrl) {
-  const note = `> **project_slug for every call:** \`${slug}\`\n\n`;
-
-  const fm = (name, description) => `---\nname: ${name}\ndescription: ${description}\n---\n\n`;
-
-  return [
-    {
-      name: "opensddrag-propose",
-      content: `${fm("opensddrag-propose", "Create a named change proposal — entry point for every feature or bugfix")}# OpenSddRag — Propose
-${note}Creates a named **change** with a proposal artifact: Why, What Changes, Capabilities, Impact.
-Entry point for every new feature or bugfix. No code is written here.
-After this, /opsr:spec and /opsr:design become available.
-
-**Run:** \`/opsr:propose <change-name or description>\`
-
-**Creates:** \`<change-name>-proposal\` artifact in database.
-**Unlocks:** /opsr:spec, /opsr:design
-`,
-    },
-    {
-      name: "opensddrag-spec",
-      content: `${fm("opensddrag-spec", "Write capability specs with SHALL/MUST requirements and WHEN/THEN scenarios")}# OpenSddRag — Spec
-${note}Creates spec artifacts for each capability listed in the proposal.
-Uses SHALL/MUST language. Each requirement MUST have Scenarios with WHEN/THEN format.
-
-**New capability** → full spec (Purpose + Requirements + Scenarios)
-**Modified capability** → delta spec (ADDED / MODIFIED / REMOVED / RENAMED sections)
-
-**Run:** \`/opsr:spec <change-name>\`
-
-**Requires:** proposal artifact in database.
-**Creates:** \`<change-name>-<capability>-spec\` artifact(s) in database.
-**Unlocks:** /opsr:design (when all capabilities have specs)
-`,
-    },
-    {
-      name: "opensddrag-design",
-      content: `${fm("opensddrag-design", "Document technical decisions, architecture, and trade-offs for a change")}# OpenSddRag — Design
-${note}Creates a design document: Context, Goals, Decisions (with alternatives), Architecture, Risks, Migration.
-Must read proposal and all specs from the database as context.
-
-**Run:** \`/opsr:design <change-name>\`
-
-**Requires:** proposal + specs in database.
-**Creates:** \`<change-name>-design\` artifact in database.
-**Unlocks:** /opsr:tasks
-`,
-    },
-    {
-      name: "opensddrag-tasks",
-      content: `${fm("opensddrag-tasks", "Break a design into atomic, verifiable implementation tasks")}# OpenSddRag — Tasks
-${note}Decomposes specs + design into atomic task artifacts, each < 4 hours.
-Each task has: Goal, Acceptance criteria (referencing REQ-NNN), Dependencies.
-Tasks are individual database artifacts — NOT a single markdown file.
-
-**Run:** \`/opsr:tasks <change-name>\`
-
-**Requires:** proposal + specs + design in database.
-**Creates:** \`<change-name>-task-<N>\` artifacts in database.
-**Unlocks:** /opsr:apply
-`,
-    },
-    {
-      name: "opensddrag-apply",
-      content: `${fm("opensddrag-apply", "Implement the next pending task against spec acceptance criteria")}# OpenSddRag — Apply
-${note}Implements tasks one at a time, reading ALL planning artifacts (proposal + specs + design) as context.
-Marks tasks active → archived in the database after implementation.
-Must validate each task against spec acceptance criteria before marking done.
-
-**Run:** \`/opsr:apply <change-name>\`
-
-**Requires:** all planning artifacts + pending tasks in database.
-**Updates:** task status in database (draft → active → archived).
-**After all tasks:** run /opsr:verify then /opsr:archive.
-`,
-    },
-    {
-      name: "opensddrag-verify",
-      content: `${fm("opensddrag-verify", "Validate implementation against spec requirements and design decisions")}# OpenSddRag — Verify
-${note}Read-only validation of the implementation against spec requirements and design decisions.
-Produces a report with CRITICAL / WARNING / SUGGESTION severity levels.
-
-Checks:
-- **Completeness**: all tasks done, all REQ-NNN implemented
-- **Correctness**: all spec scenarios covered
-- **Coherence**: implementation follows design decisions
-
-**Run:** \`/opsr:verify <change-name>\`
-
-**Requires:** all artifacts in database + implementation in codebase.
-**Output:** verification report (no artifacts modified).
-`,
-    },
-    {
-      name: "opensddrag-sync",
-      content: `${fm("opensddrag-sync", "Merge delta specs back into main capability specs")}# OpenSddRag — Sync
-${note}Merges delta specs (ADDED/MODIFIED/REMOVED/RENAMED) into main specs stored in the database.
-Called automatically during /opsr:archive when delta specs exist.
-
-Delta operations:
-- **ADDED** → append new requirement to main spec
-- **MODIFIED** → apply partial updates (not wholesale replace)
-- **REMOVED** → delete requirement + add Reason/Migration note
-- **RENAMED** → rename requirement heading
-
-**Run:** \`/opsr:sync <change-name>\`
-
-**Requires:** delta specs + main specs in database.
-**Updates:** main spec artifacts in database.
-`,
-    },
-    {
-      name: "opensddrag-archive",
-      content: `${fm("opensddrag-archive", "Finalize a completed change by archiving all its artifacts")}# OpenSddRag — Archive
-${note}Finalizes a completed change: validates, syncs delta specs, archives all artifacts.
-
-Steps:
-1. Validate artifact and task completion (warns if incomplete)
-2. Sync delta specs to main specs (if any)
-3. Mark all change artifacts as archived in database
-
-**Run:** \`/opsr:archive <change-name>\`
-
-**Requires:** all tasks completed (or user confirmation to archive anyway).
-**Updates:** all change artifacts to status=archived in database.
-`,
-    },
-    {
-      name: "opensddrag-explore",
-      content: `${fm("opensddrag-explore", "Investigate a problem or idea without writing any code")}# OpenSddRag — Explore
-${note}Thinking mode — investigates ideas WITHOUT implementing any code.
-Reads existing specs and codebase for context. Can create artifacts to capture insights.
-
-Rules:
-- NEVER write application code
-- NEVER create implementation files
-- MAY create/update OpenSddRag artifacts to capture decisions
-
-Use when: thinking through options, investigating feasibility, comparing approaches.
-Transition: when ready → /opsr:propose <name>
-
-**Run:** \`/opsr:explore <topic or question>\`
-`,
-    },
-    {
-      name: "opensddrag-continue",
-      content: `${fm("opensddrag-continue", "Create the next single artifact in the SDD dependency chain")}# OpenSddRag — Continue
-${note}Creates the NEXT SINGLE artifact in the dependency chain and stops.
-Unlike /opsr:flow, creates one artifact per invocation.
-
-Dependency order: proposal → specs → design → tasks
-
-Use when: stepping through the SDD flow one artifact at a time.
-
-**Run:** \`/opsr:continue <change-name>\`
-`,
-    },
-    {
-      name: "opensddrag-status",
-      content: `${fm("opensddrag-status", "Show current state of all in-progress changes")}# OpenSddRag — Status
-${note}Shows current state of all in-progress changes: artifact completion, task progress, recent activity.
-
-Reads from MCP server — no local files.
-
-**Run:** \`/opsr:status\` or \`/opsr:status <change-name>\`
-`,
-    },
-    {
-      name: "opensddrag-flow",
-      content: `${fm("opensddrag-flow", "Run the complete SDD flow end-to-end in one session")}# OpenSddRag — Flow
-${note}Runs the complete SDD flow end-to-end: propose → spec → design → tasks → apply → archive.
-ALL artifacts saved to database via MCP — no local files created.
-
-Use when: implementing a feature from scratch in a single session.
-
-**Run:** \`/opsr:flow <feature description>\`
-`,
-    },
-    {
-      name: "opensddrag-search",
-      content: `${fm("opensddrag-search", "Semantic search over specs, tasks, and past agent actions")}# OpenSddRag — Search
-${note}Semantic search over the SDD knowledge base using pgvector similarity.
-Always run this BEFORE starting new work to find existing specs and decisions.
-
-Searches: this project first, then all projects if no results.
-Also recalls past agent actions (episodic memory).
-
-**Run:** \`/opsr:search <natural language query>\`
-`,
-    },
-  ];
-}
-
+/**
+ * OpenSddRag skill templates — aggregator.
+ *
+ * Each of the 13 SDD skills lives in its own module exporting
+ * { name, description, body(slug, note) }. This file wraps every body with the
+ * Claude Code or OpenCode header (`note`) plus YAML frontmatter, so the workflow
+ * is authored once per skill and the CC/OC pair is always in sync
+ * (command-skill-separation-contract REQ-001). The public API —
+ * getSkills(slug, serverUrl) and getOpenCodeSkills(slug, serverUrl) — is
+ * unchanged, so client/src/commands/init.js needs no edits.
+ */
+
+import { proposeSkill } from "./propose.js";
+import { specSkill } from "./spec.js";
+import { designSkill } from "./design.js";
+import { tasksSkill } from "./tasks.js";
+import { applySkill } from "./apply.js";
+import { verifySkill } from "./verify.js";
+import { syncSkill } from "./sync.js";
+import { archiveSkill } from "./archive.js";
+import { exploreSkill } from "./explore.js";
+import { continueSkill } from "./continue.js";
+import { statusSkill } from "./status.js";
+import { flowSkill } from "./flow.js";
+import { searchSkill } from "./search.js";
+
+const SKILLS = [
+  proposeSkill,
+  specSkill,
+  designSkill,
+  tasksSkill,
+  applySkill,
+  verifySkill,
+  syncSkill,
+  archiveSkill,
+  exploreSkill,
+  continueSkill,
+  statusSkill,
+  flowSkill,
+  searchSkill,
+];
+
+const frontmatter = (name, description) =>
+  `---\nname: ${name}\ndescription: ${description}\n---\n\n`;
+
+/**
+ * Claude Code skills — installed to .claude/skills/ and .agents/skills/.
+ * Header advertises the MCP server + tool list and the STOP-if-not-connected rule.
+ */
 export function getSkills(slug, serverUrl) {
   const note = `> **MCP server:** \`opensddrag\` (${serverUrl}) | **project_slug:** \`${slug}\`
-> **Available tools:** \`create_artifact\`, \`read_artifact\`, \`list_artifacts\`, \`update_artifact\`, \`validate_artifact\`, \`link_artifacts\`, \`get_relationships\`, \`search_semantic\`, \`recall_episodes\`, \`get_working_context\`, \`update_working_context\`, \`record_trace\`
+> **Available tools:** \`create_artifact\`, \`read_artifact\`, \`list_artifacts\`, \`read_change_bundle\`, \`update_artifact\`, \`validate_artifact\`, \`link_artifacts\`, \`get_relationships\`, \`search_semantic\`, \`recall_episodes\`, \`get_working_context\`, \`update_working_context\`, \`record_trace\`, \`get_harness_checklist\`
 > If these tools are not in your active tool list, the \`opensddrag\` MCP server is not connected — STOP and inform the user.\n\n`;
 
-  const fm = (name, description) => `---\nname: ${name}\ndescription: ${description}\n---\n\n`;
-
-  return [
-    {
-      name: "opensddrag-propose",
-      content: `${fm("opensddrag-propose", "Create a named change proposal — entry point for every feature or bugfix")}# OpenSddRag — Propose
-${note}Creates a named **change** with a proposal artifact: Why, What Changes, Capabilities, Impact.
-Entry point for every new feature or bugfix. No code is written here.
-After this, /opsr:spec and /opsr:design become available.
-
-**Run:** \`/opsr:propose <change-name or description>\`
-
-**Creates:** \`<change-name>-proposal\` artifact in database.
-**Unlocks:** /opsr:spec, /opsr:design
-`,
-    },
-    {
-      name: "opensddrag-spec",
-      content: `${fm("opensddrag-spec", "Write capability specs with SHALL/MUST requirements and WHEN/THEN scenarios")}# OpenSddRag — Spec
-${note}Creates spec artifacts for each capability listed in the proposal.
-Uses SHALL/MUST language. Each requirement MUST have Scenarios with WHEN/THEN format.
-
-**New capability** → full spec (Purpose + Requirements + Scenarios)
-**Modified capability** → delta spec (ADDED / MODIFIED / REMOVED / RENAMED sections)
-
-**Run:** \`/opsr:spec <change-name>\`
-
-**Requires:** proposal artifact in database.
-**Creates:** \`<change-name>-<capability>-spec\` artifact(s) in database.
-**Unlocks:** /opsr:design (when all capabilities have specs)
-`,
-    },
-    {
-      name: "opensddrag-design",
-      content: `${fm("opensddrag-design", "Document technical decisions, architecture, and trade-offs for a change")}# OpenSddRag — Design
-${note}Creates a design document: Context, Goals, Decisions (with alternatives), Architecture, Risks, Migration.
-Must read proposal and all specs from the database as context.
-
-**Run:** \`/opsr:design <change-name>\`
-
-**Requires:** proposal + specs in database.
-**Creates:** \`<change-name>-design\` artifact in database.
-**Unlocks:** /opsr:tasks
-`,
-    },
-    {
-      name: "opensddrag-tasks",
-      content: `${fm("opensddrag-tasks", "Break a design into atomic, verifiable implementation tasks")}# OpenSddRag — Tasks
-${note}Decomposes specs + design into atomic task artifacts, each < 4 hours.
-Each task has: Goal, Acceptance criteria (referencing REQ-NNN), Dependencies.
-Tasks are individual database artifacts — NOT a single markdown file.
-
-**Run:** \`/opsr:tasks <change-name>\`
-
-**Requires:** proposal + specs + design in database.
-**Creates:** \`<change-name>-task-<N>\` artifacts in database.
-**Unlocks:** /opsr:apply
-`,
-    },
-    {
-      name: "opensddrag-apply",
-      content: `${fm("opensddrag-apply", "Implement the next pending task against spec acceptance criteria")}# OpenSddRag — Apply
-${note}Implements tasks one at a time, reading ALL planning artifacts (proposal + specs + design) as context.
-Marks tasks active → archived in the database after implementation.
-Must validate each task against spec acceptance criteria before marking done.
-
-**Run:** \`/opsr:apply <change-name>\`
-
-**Requires:** all planning artifacts + pending tasks in database.
-**Updates:** task status in database (draft → active → archived).
-**After all tasks:** run /opsr:verify then /opsr:archive.
-`,
-    },
-    {
-      name: "opensddrag-verify",
-      content: `${fm("opensddrag-verify", "Validate implementation against spec requirements and design decisions")}# OpenSddRag — Verify
-${note}Read-only validation of the implementation against spec requirements and design decisions.
-Produces a report with CRITICAL / WARNING / SUGGESTION severity levels.
-
-Checks:
-- **Completeness**: all tasks done, all REQ-NNN implemented
-- **Correctness**: all spec scenarios covered
-- **Coherence**: implementation follows design decisions
-
-**Run:** \`/opsr:verify <change-name>\`
-
-**Requires:** all artifacts in database + implementation in codebase.
-**Output:** verification report (no artifacts modified).
-`,
-    },
-    {
-      name: "opensddrag-sync",
-      content: `${fm("opensddrag-sync", "Merge delta specs back into main capability specs")}# OpenSddRag — Sync
-${note}Merges delta specs (ADDED/MODIFIED/REMOVED/RENAMED) into main specs stored in the database.
-Called automatically during /opsr:archive when delta specs exist.
-
-Delta operations:
-- **ADDED** → append new requirement to main spec
-- **MODIFIED** → apply partial updates (not wholesale replace)
-- **REMOVED** → delete requirement + add Reason/Migration note
-- **RENAMED** → rename requirement heading
-
-**Run:** \`/opsr:sync <change-name>\`
-
-**Requires:** delta specs + main specs in database.
-**Updates:** main spec artifacts in database.
-`,
-    },
-    {
-      name: "opensddrag-archive",
-      content: `${fm("opensddrag-archive", "Finalize a completed change by archiving all its artifacts")}# OpenSddRag — Archive
-${note}Finalizes a completed change: validates, syncs delta specs, archives all artifacts.
-
-Steps:
-1. Validate artifact and task completion (warns if incomplete)
-2. Sync delta specs to main specs (if any)
-3. Mark all change artifacts as archived in database
-
-**Run:** \`/opsr:archive <change-name>\`
-
-**Requires:** all tasks completed (or user confirmation to archive anyway).
-**Updates:** all change artifacts to status=archived in database.
-`,
-    },
-    {
-      name: "opensddrag-explore",
-      content: `${fm("opensddrag-explore", "Investigate a problem or idea without writing any code")}# OpenSddRag — Explore
-${note}Thinking mode — investigates ideas WITHOUT implementing any code.
-Reads existing specs and codebase for context. Can create artifacts to capture insights.
-
-Rules:
-- NEVER write application code
-- NEVER create implementation files
-- MAY create/update OpenSddRag artifacts to capture decisions
-
-Use when: thinking through options, investigating feasibility, comparing approaches.
-Transition: when ready → /opsr:propose <name>
-
-**Run:** \`/opsr:explore <topic or question>\`
-`,
-    },
-    {
-      name: "opensddrag-continue",
-      content: `${fm("opensddrag-continue", "Create the next single artifact in the SDD dependency chain")}# OpenSddRag — Continue
-${note}Creates the NEXT SINGLE artifact in the dependency chain and stops.
-Unlike /opsr:flow, creates one artifact per invocation.
-
-Dependency order: proposal → specs → design → tasks
-
-Use when: stepping through the SDD flow one artifact at a time.
-
-**Run:** \`/opsr:continue <change-name>\`
-`,
-    },
-    {
-      name: "opensddrag-status",
-      content: `${fm("opensddrag-status", "Show current state of all in-progress changes")}# OpenSddRag — Status
-${note}Shows current state of all in-progress changes: artifact completion, task progress, recent activity.
-
-Reads from MCP server — no local files.
-
-**Run:** \`/opsr:status\` or \`/opsr:status <change-name>\`
-`,
-    },
-    {
-      name: "opensddrag-flow",
-      content: `${fm("opensddrag-flow", "Run the complete SDD flow end-to-end in one session")}# OpenSddRag — Flow
-${note}Runs the complete SDD flow end-to-end: propose → spec → design → tasks → apply → archive.
-ALL artifacts saved to database via MCP — no local files created.
-
-Use when: implementing a feature from scratch in a single session.
-
-**Run:** \`/opsr:flow <feature description>\`
-`,
-    },
-    {
-      name: "opensddrag-search",
-      content: `${fm("opensddrag-search", "Semantic search over specs, tasks, and past agent actions")}# OpenSddRag — Search
-${note}Semantic search over the SDD knowledge base using pgvector similarity.
-Always run this BEFORE starting new work to find existing specs and decisions.
+  return SKILLS.map((skill) => ({
+    name: skill.name,
+    content: `${frontmatter(skill.name, skill.description)}${skill.body(slug, note)}`,
+  }));
+}
 
-Searches: this project first, then all projects if no results.
-Also recalls past agent actions (episodic memory).
+/**
+ * OpenCode skills — installed to .opencode/skills/.
+ * Compact header (project_slug only); MCP tools are auto-available in OpenCode.
+ */
+export function getOpenCodeSkills(slug, _serverUrl) {
+  const note = `> **project_slug for every call:** \`${slug}\`\n\n`;
 
-**Run:** \`/opsr:search <natural language query>\`
-`,
-    },
-  ];
+  return SKILLS.map((skill) => ({
+    name: skill.name,
+    content: `${frontmatter(skill.name, skill.description)}${skill.body(slug, note)}`,
+  }));
 }

package/src/templates/skills/propose.js

@@ -0,0 +1,74 @@
+export const proposeSkill = {
+  name: "opensddrag-propose",
+  description:
+    "Create a named change proposal — entry point for every feature or bugfix",
+  body: (slug, note) => `# OpenSddRag — Propose
+${note}## When to use
+Run this as the entry point for every new feature or bugfix, before any code is written.
+It creates a named **change** with a proposal artifact defining WHY, WHAT changes, WHICH
+capabilities are affected, and the IMPACT. After it, /opsr:spec and /opsr:design unlock.
+
+## Inputs
+$ARGUMENTS = change name (kebab-case) or a plain description. If a plain description, derive a kebab-case name.
+
+## Workflow
+
+### Step 1 — Derive the change name
+If $ARGUMENTS is a plain description (contains spaces), convert it to kebab-case.
+Example: "add user authentication" → "add-user-authentication".
+
+### Step 2 — Search for existing work (avoid duplication)
+\`search_semantic(query="$ARGUMENTS", project_slug="${slug}", limit=5)\`
+If relevant artifacts are found, show them and ask the user to confirm this is genuinely new work.
+
+### Step 3 — Write the proposal content
+Compose this structure — do NOT skip any section:
+
+\`\`\`markdown
+# <change-name>
+
+## Why
+[1-2 sentences on the problem or opportunity being addressed]
+
+## What Changes
+- [Specific change 1]
+- [Specific change 2]
+- **BREAKING** [Breaking change if any]
+
+## Capabilities
+### New Capabilities
+- [capability-name] — brief description
+
+### Modified Capabilities
+- [existing-capability] — what changes
+
+## Impact
+[Affected code, APIs, dependencies, systems]
+\`\`\`
+
+### Step 4 — Save the proposal
+\`create_artifact(name="<change-name>-proposal", type="proposal", content="<full proposal markdown>", metadata={"change_name": "<change-name>", "status_phase": "planning"}, project_slug="${slug}")\`
+Note the returned artifact ID.
+
+### Step 5 — Create spec drafts for each capability
+Parse "## Capabilities". For each capability in "New Capabilities" or "Modified Capabilities":
+1. Check if a spec already exists: \`read_artifact(name="<change-name>-<capability>-spec", project_slug="${slug}")\`. If it exists and is non-empty, skip.
+2. Otherwise create a draft spec scaffold:
+\`create_artifact(name="<change-name>-<capability>-spec", type="spec", status="draft", content="# <capability> Specification\\n\\n## Purpose\\n[TODO]\\n\\n## Requirements\\n\\n### Requirement: REQ-001\\n[TODO SHALL/MUST]\\n\\n#### Scenario: <Name>\\n- **WHEN** [condition]\\n- **THEN** [outcome]", metadata={"change_name": "<change-name>", "capability": "<capability>", "is_delta": true}, project_slug="${slug}")\`
+
+### Step 6 — Create a design skeleton
+\`create_artifact(name="<change-name>-design", type="design", status="draft", content="# Design: <change-name>\\n\\n## Context\\n[TODO]\\n\\n## Goals / Non-Goals\\n\\n## Decisions\\n\\n## Architecture\\n\\n## Risks / Trade-offs\\n\\n## Open Questions", metadata={"change_name": "<change-name>"}, project_slug="${slug}")\`
+
+### Step 7 — Record the action
+\`record_trace(action="propose", result_summary="Created proposal: <change-name>-proposal", project_slug="${slug}")\`
+
+## Output
+- A \`<change-name>-proposal\` artifact (plus draft spec/design scaffolds) in the database.
+- **Unlocks:** /opsr:spec, /opsr:design, or /opsr:flow to continue automatically.
+
+## Important rules
+- NEVER write application code in this phase.
+- DO NOT create local markdown files — all artifacts live in the database.
+- If $ARGUMENTS is empty, ask the user for a change name or description before proceeding.
+`,
+};

package/src/templates/skills/search.js

@@ -0,0 +1,60 @@
+export const searchSkill = {
+  name: "opensddrag-search",
+  description: "Semantic search over specs, tasks, and past agent actions",
+  body: (slug, note) => `# OpenSddRag — Search
+${note}## When to use
+To search the SDD knowledge base by semantic similarity (pgvector). Run this BEFORE starting any
+new work to find existing specs, decisions, and past implementations.
+
+## Inputs
+$ARGUMENTS = natural language search query.
+
+## Workflow
+
+### Step 1 — Search this project
+\`search_semantic(query="$ARGUMENTS", project_slug="${slug}", limit=5)\`
+
+### Step 2 — If no relevant results, search all projects
+\`search_semantic(query="$ARGUMENTS", project_slug="*", limit=5)\`
+
+### Step 3 — Recall past actions related to the query
+\`recall_episodes(query="$ARGUMENTS", project_slug="${slug}", limit=3)\`
+
+### Step 4 — Present the results clearly
+For each result: name, type, status, and a content excerpt (first ~200 chars).
+Group by: this project / other projects / past actions.
+
+### Step 5 — Offer to read a full artifact
+\`read_artifact(name="<artifact-name>", project_slug="${slug}")\`
+
+### Step 6 — Optionally filter by artifact type
+When the user is only interested in one kind of artifact, narrow the search:
+\`search_semantic(query="$ARGUMENTS", project_slug="${slug}", type="spec", limit=5)\`
+Valid \`type\` values: \`proposal\`, \`spec\`, \`design\`, \`task\`.
+
+## Examples
+- "How do we handle delta specs?" → finds the spec/sync capability artifacts.
+- "auth token refresh" → finds proposals/specs/designs touching authentication.
+- "what did we decide about embeddings" → combine with \`recall_episodes\` for past decisions.
+
+A good presentation block looks like:
+\`\`\`
+### This project
+- [spec] opensddrag-sync-spec (active) — "Merges delta specs (ADDED/MODIFIED/REMOVED…)"
+### Other projects
+- (none)
+### Past actions
+- design (2026-06-22) — "Created design: refactor-commands-skills-separation-design"
+\`\`\`
+
+## Output
+- A grouped list of semantically relevant artifacts and past actions, with an offer to open any.
+
+## Important rules
+- Read-only — search never creates or modifies artifacts.
+- Fall back to cross-project search (project_slug="*") only when the local search is empty.
+- Surface episodic recall alongside artifacts so prior decisions are not missed.
+- Prefer specific, noun-rich queries; vague one-word queries return weak matches.
+- Always run search BEFORE /opsr:propose to avoid creating duplicate changes.
+`,
+};