opensddrag 0.1.1 → 0.2.0

package/src/templates/skills/index.js

@@ -1,192 +1,72 @@
+/**
+ * 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\`, \`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`;
 
-  return [
-    {
-      name: "opensddrag-propose",
-      content: `# 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: `# 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: `# 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: `# 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: `# 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: `# 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: `# 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: `# 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: `# 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: `# 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: `# 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: `# 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: `# 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).
+  return SKILLS.map((skill) => ({
+    name: skill.name,
+    content: `${frontmatter(skill.name, skill.description)}${skill.body(slug, note)}`,
+  }));
+}
 
-**Run:** \`/opsr:search <natural language query>\`
-`,
-    },
-  ];
+/**
+ * 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`;
+
+  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.
+`,
+};

package/src/templates/skills/spec.js

@@ -0,0 +1,94 @@
+import { harnessChecklistBlock } from "./_shared.js";
+
+export const specSkill = {
+  name: "opensddrag-spec",
+  description:
+    "Write capability specs with SHALL/MUST requirements and WHEN/THEN scenarios",
+  body: (slug, note) => `# OpenSddRag — Spec
+${note}## When to use
+After a proposal exists, to formalize each capability into a spec artifact with SHALL/MUST
+requirements and WHEN/THEN scenarios. Each capability in the proposal gets its own spec.
+
+## Inputs
+$ARGUMENTS = change name. If not provided, list proposals and ask which one.
+
+## Workflow
+
+### Step 1 — Read the proposal
+\`list_artifacts(type="proposal", project_slug="${slug}")\`
+\`read_artifact(name="<change-name>-proposal", project_slug="${slug}")\`
+
+### Step 2 — Identify capabilities
+Parse "## Capabilities". Every capability in "New Capabilities" and "Modified Capabilities" needs a spec.
+- **New capability** → full spec (Purpose + Requirements + Scenarios).
+- **Modified capability** → check for an existing main spec: \`search_semantic(query="<capability> spec", project_slug="${slug}", limit=3)\`.
+  - If a main spec exists → create a DELTA spec (ADDED/MODIFIED/REMOVED/RENAMED).
+  - If no main spec → create BOTH the main spec (is_delta=false) and the delta spec (is_delta=true).
+
+### Step 3 — Write spec content for each capability
+
+Full spec structure (new capabilities):
+\`\`\`markdown
+# <capability> Specification
+
+## Purpose
+[High-level description]
+
+## Requirements
+
+### Requirement: REQ-001 <Name>
+[Description using SHALL/MUST language]
+
+#### Scenario: <Happy path>
+- **WHEN** [condition]
+- **THEN** [expected outcome]
+
+#### Scenario: <Edge case>
+- **WHEN** [edge condition]
+- **THEN** [expected outcome]
+\`\`\`
+
+Delta spec structure (modified capabilities):
+\`\`\`markdown
+# <capability> Specification — Delta
+
+## ADDED Requirements
+### Requirement: <New name>
+[Full requirement with scenarios]
+
+## MODIFIED Requirements
+### Requirement: <Existing name>
+[Full updated text with all scenarios]
+
+## REMOVED Requirements
+### Requirement: <Removed name>
+**Reason:** [why] · **Migration:** [how consumers migrate]
+
+## RENAMED Requirements
+- FROM: \`### Requirement: Old Name\`
+- TO: \`### Requirement: New Name\`
+\`\`\`
+
+### Step 4 — Save each spec
+\`create_artifact(name="<change-name>-<capability>-spec", type="spec", content="<full spec markdown>", metadata={"change_name": "<change-name>", "capability": "<capability>", "is_delta": true|false}, project_slug="${slug}")\`
+
+### Step 5 — Link each spec to the proposal
+\`link_artifacts(source_name="<spec>", target_name="<change-name>-proposal", relationship_type="implements", project_slug="${slug}")\`
+
+### Step 6 — Validate each spec
+\`validate_artifact(name="<spec>", project_slug="${slug}")\` — fix any validation errors before continuing.
+
+${harnessChecklistBlock(slug, "on_spec", "Saving specs to the database")}
+### Step 7 — Record the action
+\`record_trace(action="spec", result_summary="Created specs for: <capability-list>", project_slug="${slug}")\`
+
+## Output
+- One spec artifact per capability (full and/or delta) linked to the proposal.
+- **Unlocks:** /opsr:design once all capabilities have specs.
+
+## Important rules
+- Every requirement MUST have at least one WHEN/THEN scenario.
+- Delta specs MUST carry metadata.is_delta=true so /opsr:sync can merge them later.
+- Run the harness checklist (on_spec) before declaring specs done.
+`,
+};

package/src/templates/skills/status.js

@@ -0,0 +1,66 @@
+export const statusSkill = {
+  name: "opensddrag-status",
+  description: "Show current state of all in-progress changes",
+  body: (slug, note) => `# OpenSddRag — Status
+${note}## When to use
+To show the current state of all in-progress changes for this project: artifact completion,
+task progress, and recent activity. Reads from the MCP server — no local files involved.
+
+## Inputs
+$ARGUMENTS = optional change name to show details for a single change. If absent, show all.
+
+## Workflow
+
+### Step 1 — Load working context
+\`get_working_context(project_slug="${slug}")\`
+This also surfaces any \`trigger="always"\` harness rules — read them first.
+
+### Step 2 — List artifacts by type and status
+\`list_artifacts(type="proposal", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="proposal", status="draft", project_slug="${slug}")\`
+\`list_artifacts(type="spec", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="design", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="task", status="active", project_slug="${slug}")\`
+\`list_artifacts(type="task", status="draft", project_slug="${slug}")\`
+
+### Step 3 — Recall recent activity
+\`recall_episodes(query="recent actions in this project", project_slug="${slug}", limit=5)\`
+
+### Step 4 — Present a structured status
+For each active change, show:
+\`\`\`
+## Change: <change-name>
+| Artifact | Status |
+|----------|--------|
+| Proposal | ✓ done |
+| Specs    | ✓ 2/2  |
+| Design   | ✓ done |
+| Tasks    | 3/5 done |
+
+Current task: <task-name>
+Next step: /opsr:apply <change-name>
+\`\`\`
+Then show recent activity (last 5 episodes) and a suggested next command based on the state.
+
+### Step 5 — Suggest the next command
+Map the change's state to the next action:
+- proposal only → /opsr:spec
+- specs but no design → /opsr:design
+- design but no tasks → /opsr:tasks
+- tasks with drafts remaining → /opsr:apply
+- all tasks archived → /opsr:verify then /opsr:archive
+
+## Reading the working context
+\`get_working_context\` returns \`current_task\` and the ordered \`tasks\` list — use them to compute
+"N/M done" and to name the in-flight task. It also returns always-trigger harness rules; show
+those at the top so the user starts every session aware of the project's constraints.
+
+## Output
+- A per-change status table, recent activity, and the recommended next command.
+
+## Important rules
+- Read-only — never modify artifacts from status.
+- If a specific change is requested, scope all lists to that change via metadata.change_name.
+- Always surface always-trigger harness rules from the working context.
+`,
+};

package/src/templates/skills/sync.js

@@ -0,0 +1,65 @@
+export const syncSkill = {
+  name: "opensddrag-sync",
+  description: "Merge delta specs back into main capability specs",
+  body: (slug, note) => `# OpenSddRag — Sync
+${note}## When to use
+To merge delta specs (ADDED/MODIFIED/REMOVED/RENAMED) into the main specs stored in the database.
+Delta specs are created by /opsr:spec for MODIFIED capabilities. Runs automatically during /opsr:archive.
+
+## Inputs
+$ARGUMENTS = change name.
+
+## Workflow
+
+### Step 1 — Find delta specs for this change
+\`list_artifacts(type="spec", project_slug="${slug}")\`
+Filter where metadata.change_name = "<change-name>" AND metadata.is_delta = true.
+
+### Step 2 — For each delta, find the main spec
+\`search_semantic(query="<capability> spec", project_slug="${slug}", limit=5)\`
+Find the spec for the same capability where metadata.is_delta = false (or unset).
+
+### Step 3 — Apply delta operations to the main spec
+\`read_artifact(name="<delta-spec>", project_slug="${slug}")\`
+\`read_artifact(name="<main-spec>", project_slug="${slug}")\`
+Apply each delta section:
+- **## ADDED Requirements** → confirm the requirement does NOT exist, then append it (with scenarios).
+- **## MODIFIED Requirements** → find by name and apply ONLY the changed parts (partial update, not wholesale replace).
+- **## REMOVED Requirements** → remove the requirement block; note the Reason/Migration in a comment.
+- **## RENAMED Requirements** → change the heading FROM the old name TO the new name.
+
+### Step 4 — Save the updated main spec
+\`update_artifact(name="<main-spec>", content="<merged spec content>", project_slug="${slug}")\`
+
+### Step 5 — Archive the delta spec
+\`update_artifact(name="<delta-spec>", status="archived", metadata={"synced_at": "<ISO timestamp>", "merged_into": "<main-spec>"}, project_slug="${slug}")\`
+
+### Step 6 — Record the sync
+\`record_trace(action="sync", result_summary="Synced delta for capability: <capability> into main spec", project_slug="${slug}")\`
+Tell the user which capabilities were updated.
+
+## Worked example — a MODIFIED merge
+Delta says:
+\`\`\`markdown
+## MODIFIED Requirements
+### Requirement: REQ-002 Token issuance
+[adds a new scenario for refresh tokens]
+\`\`\`
+Main spec already has REQ-002 with two scenarios. Correct merge = keep the existing two scenarios
+and APPEND the new refresh-token scenario under the same requirement heading. Do NOT replace the
+whole REQ-002 block — that would silently drop the original scenarios.
+
+## When NOT to sync
+- The delta is still being edited (run /opsr:spec to completion first).
+- No main spec exists yet for the capability — then there is nothing to merge into; the delta
+  IS the spec until a main is created.
+
+## Output
+- Main spec artifacts updated to reflect all deltas; delta specs archived with a merge pointer.
+
+## Important rules
+- MODIFIED requirements get partial, intelligent merges — never blind whole-section replacement.
+- Always archive the delta after merging so it is not re-applied.
+- Preserve REMOVED requirements' Reason/Migration as a note for future readers.
+`,
+};