opensddrag 0.1.0 → 0.1.2

package/src/templates/skill-md.js

@@ -1,3 +1,183 @@
+export function getHarnessSkill({ slug, serverUrl }) {
+  // SKILL.md for the `opensddrag-harness` skill — installed into
+  // .claude/skills/opensddrag-harness/ and .agents/skills/opensddrag-harness/
+  // by `opensddrag init`. Drives the /opsr:harness slash command behaviorally
+  // for both Claude Code and OpenCode, using only the standard MCP tools
+  // (add_rule, list_rules, get_harness_checklist). No direct DB access, no
+  // local file writes for rule storage — rules are persisted via the MCP
+  // server's `project_rules` table.
+  return `---
+name: opensddrag-harness
+description: Manage persistent project rules — add, list, and disable behavioral constraints
+---
+
+# OpenSddRag — Harness
+
+This project is connected to the OpenSddRag Harness (${serverUrl}).
+The Harness layer manages **project rules**: persistent, per-project behavioral
+constraints that are automatically injected into every agent session.
+
+## Project slug: \`${slug}\`
+
+Always pass \`project_slug: "${slug}"\` to scope rule operations to this project.
+
+## When to use
+
+- Before starting any new feature, ask: "Are there harness rules I should be aware of?"
+  \`get_working_context(project_slug="${slug}")\` will return any \`trigger="always"\` rules
+  automatically — read them first.
+- Use \`/opsr:harness\` (Claude Code) or invoke this skill (OpenCode) to:
+  - **add** a new rule (architecture, naming, forbidden, doc-sync, verification)
+  - **list** all rules for the project, grouped by trigger
+  - **disable** a rule (soft-delete — re-enable by re-adding with the same name)
+
+## Available operations
+
+### add — create or update a project rule
+
+Call the \`add_rule\` MCP tool. Required arguments:
+
+\`\`\`
+add_rule(
+  name:        "<kebab-case-name>",
+  trigger:     "always" | "on_apply" | "on_verify" | "on_archive" | "on_spec",
+  category:    "architecture" | "naming" | "forbidden" | "doc-sync" | "verification",
+  severity:    "error" | "warning" | "info",   // default: "warning"
+  instruction: "<free-text rule the agent must follow>",
+  project_slug:"${slug}",
+  enabled:     true,                              // default: true (set false to soft-delete)
+  metadata:    { ... }                            // optional, free-form JSON
+)
+\`\`\`
+
+When the user provides a rule in natural language, infer the fields:
+- "always update X when applying" → trigger=\`on_apply\`, category=\`doc-sync\`, severity=\`warning\`
+- "never do Y" → trigger=\`always\`, category=\`forbidden\`, severity=\`error\`
+- "use Z pattern in this project" → trigger=\`always\`, category=\`architecture\`, severity=\`warning\`
+
+**Example 1 — architecture rule (always):**
+\`\`\`
+add_rule(
+  name:        "repo-pattern-required",
+  trigger:     "always",
+  category:    "architecture",
+  severity:    "error",
+  instruction: "All data access must go through a repository class. Do not call the ORM or DB driver directly from route handlers or service classes.",
+  project_slug:"${slug}"
+)
+\`\`\`
+
+**Example 2 — doc-sync rule (on_apply):**
+\`\`\`
+add_rule(
+  name:        "update-changelog-on-apply",
+  trigger:     "on_apply",
+  category:    "doc-sync",
+  severity:    "warning",
+  instruction: "When applying a task that ships a user-visible change, add a one-line entry to CHANGELOG.md under the unreleased section before marking the task complete.",
+  project_slug:"${slug}"
+)
+\`\`\`
+
+Confirm with the user after adding:
+"Rule '<name>' added. It will be [injected at every session start | checked during /opsr:apply | ...]."
+
+### list — show all rules for this project
+
+Call the \`list_rules\` MCP tool:
+
+\`\`\`
+list_rules(project_slug="${slug}", enabled_only=true)
+\`\`\`
+
+Group the results by \`trigger\` in the output:
+
+\`\`\`
+### Always (loaded at session start)
+- [architecture:error] repo-pattern-required — All data access must go through...
+
+### On Apply (checked during /opsr:apply)
+- [doc-sync:warning] update-changelog-on-apply — When applying a task...
+
+### On Verify (checked during /opsr:verify)
+- (none)
+
+### On Archive (checked during /opsr:archive)
+- (none)
+
+### On Spec (checked during /opsr:spec)
+- (none)
+\`\`\`
+
+If the result list is empty, respond:
+"No harness rules defined for this project. Run \`/opsr:harness add\` to create the first rule."
+
+### disable — soft-delete a rule
+
+Call the \`add_rule\` MCP tool with the same \`name\` and \`enabled=false\`:
+
+\`\`\`
+add_rule(name: "<rule-name>", enabled: false, project_slug: "${slug}")
+\`\`\`
+
+This is a soft-delete: the rule is preserved in the database with \`enabled=false\`
+and will no longer appear in \`list_rules\` (default \`enabled_only=true\`) or in
+\`get_working_context\` injection. To re-enable, call \`add_rule\` with the same
+name and \`enabled=true\`.
+
+Confirm with the user:
+"Rule '<name>' disabled. It will no longer appear in checklists or session context."
+
+## Phase-gate checklist — get_harness_checklist
+
+When the user runs \`/opsr:apply\`, \`/opsr:verify\`, \`/opsr:archive\`, or
+\`/opsr:spec\`, the corresponding slash command will call:
+
+\`\`\`
+get_harness_checklist(trigger="on_apply"|"on_verify"|"on_archive"|"on_spec", project_slug="${slug}")
+\`\`\`
+
+…to fetch rules that must be satisfied at that phase gate. The response is an
+array of {name, category, severity, instruction} objects ordered by severity
+(error first) then name. Rules with \`severity="error"\` MUST be completed before
+the phase is declared done; \`severity="warning"\` rules SHOULD be addressed.
+
+You do not need to call this directly — the slash commands invoke it. But you
+can use it from this skill if the user asks "what rules apply to apply?".
+
+## Memory of rule operations
+
+Every add / disable operation should be recorded in episodic memory:
+
+\`\`\`
+record_trace(action="add_rule"|"disable_rule", result_summary="Added/disabled rule: <name>", project_slug="${slug}")
+\`\`\`
+
+## MCP tools used
+
+| Tool | Purpose |
+|------|---------|
+| \`add_rule\` | Upsert a rule (create, update, or soft-delete) |
+| \`list_rules\` | List rules with optional filters |
+| \`get_harness_checklist\` | Fetch phase-gate rules for apply/verify/archive/spec |
+| \`get_working_context\` | Already returns trigger="always" rules automatically |
+| \`record_trace\` | Log harness operations to episodic memory |
+
+## Important rules for this skill
+
+- **Never write rule data to local files** — all rules live in the \`project_rules\` table.
+- **Never translate or modify the user's rule instruction** — store it verbatim.
+- **Always confirm with the user before calling \`add_rule\`** for new rules, especially when inferring fields from natural language.
+- **Soft-delete is the only way to "remove" a rule** — re-adding with the same name restores it.
+`;
+}
+
+export function getOpenCodeHarnessSkill({ slug, serverUrl }) {
+  const full = getHarnessSkill({ slug, serverUrl });
+  // OpenCode auto-discovers tools from opencode.json — the table is noise.
+  return full.replace(/\n## MCP tools used\n[\s\S]*?(?=\n## |\n$)/, '\n');
+}
+
 export function renderSkillMd({ slug, serverUrl }) {
   return `# OpenSddRag — SDD + Harness
 

package/src/templates/skills/index.js

@@ -1,12 +1,207 @@
+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>\`
+`,
+    },
+  ];
+}
+
 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\`
 > 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: `# 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.
@@ -19,7 +214,7 @@ After this, /opsr:spec and /opsr:design become available.
     },
     {
       name: "opensddrag-spec",
-      content: `# 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.
 
@@ -35,7 +230,7 @@ Uses SHALL/MUST language. Each requirement MUST have Scenarios with WHEN/THEN fo
     },
     {
       name: "opensddrag-design",
-      content: `# 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.
 
@@ -48,7 +243,7 @@ Must read proposal and all specs from the database as context.
     },
     {
       name: "opensddrag-tasks",
-      content: `# 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.
@@ -62,7 +257,7 @@ Tasks are individual database artifacts — NOT a single markdown file.
     },
     {
       name: "opensddrag-apply",
-      content: `# 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.
@@ -76,7 +271,7 @@ Must validate each task against spec acceptance criteria before marking done.
     },
     {
       name: "opensddrag-verify",
-      content: `# 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.
 
@@ -93,7 +288,7 @@ Checks:
     },
     {
       name: "opensddrag-sync",
-      content: `# 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.
 
@@ -111,7 +306,7 @@ Delta operations:
     },
     {
       name: "opensddrag-archive",
-      content: `# 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:
@@ -127,7 +322,7 @@ Steps:
     },
     {
       name: "opensddrag-explore",
-      content: `# 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.
 
@@ -144,7 +339,7 @@ Transition: when ready → /opsr:propose <name>
     },
     {
       name: "opensddrag-continue",
-      content: `# 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.
 
@@ -157,7 +352,7 @@ Use when: stepping through the SDD flow one artifact at a time.
     },
     {
       name: "opensddrag-status",
-      content: `# 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.
@@ -167,7 +362,7 @@ Reads from MCP server — no local files.
     },
     {
       name: "opensddrag-flow",
-      content: `# 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.
 
@@ -178,7 +373,7 @@ Use when: implementing a feature from scratch in a single session.
     },
     {
       name: "opensddrag-search",
-      content: `# 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.