opensddrag 0.1.1 → 0.1.2

package/src/templates/commands/opencode.js

@@ -1,28 +1,21 @@
 /**
  * OpenCode command templates
- * These commands are identical to Claude Code commands
- * Installed to .opencode/commands/opsr/ when OpenCode is selected
+ * Installed to .opencode/commands/opsr/ when OpenCode is selected.
+ * Uses a compact openCodeHeader() (project_slug only) instead of the Claude Code
+ * IMPORTANT/tool-list/STOP block — MCP tools are auto-available in OpenCode.
  */
 
-export function getOpenCodeCommands(slug, serverUrl) {
-  const header = (name) => `> **IMPORTANT — ${name}**
-> This command requires the **\`opensddrag\`** MCP server (${serverUrl}), configured in \`opencode.json\`.
-> MCP tools provided by this server: \`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**: STOP immediately. Do NOT investigate or try alternatives. Tell the user: "The opensddrag MCP server is not connected. Please start it (\`docker compose up -d\`) and reload the project."
-> All artifact reads/writes go through these MCP tools. DO NOT create local files. DO NOT write markdown to disk.
-> **project_slug for every call: \`${slug}\`**
+export function getOpenCodeCommands(slug, _serverUrl) {
+  const fm = (description) => `---\ndescription: ${description}\n---\n\n`;
 
----
-
-
-`;
+  const openCodeHeader = () => `> **project_slug for every call:** \`${slug}\`\n\n---\n\n\n`;
 
   return [
     // ── /opsr:propose ──────────────────────────────────────────────────────────
     {
       folder: "opsr",
       name: "propose",
-      content: `${header("/opsr:propose")}## Purpose
+      content: `${fm("Create a named change proposal")}${openCodeHeader()}## Purpose
 Create a named change with a proposal artifact. This is the entry point for every new feature or change.
 The proposal defines WHY, WHAT changes, WHICH capabilities are affected, and the IMPACT.
 After this command, /opsr:spec and /opsr:design become available.
@@ -144,7 +137,7 @@ Tell the user:
     {
       folder: "opsr",
       name: "spec",
-      content: `${header("/opsr:spec")}## Purpose
+      content: `${fm("Write capability specs with requirements and scenarios")}${openCodeHeader()}## Purpose
 Create one or more spec artifacts for the capabilities listed in a proposal.
 Each capability in "New Capabilities" or "Modified Capabilities" gets its own spec artifact.
 Specs use SHALL/MUST language and must have Scenarios with WHEN/THEN format.
@@ -245,7 +238,7 @@ Fix any validation errors before continuing.
     {
       folder: "opsr",
       name: "design",
-      content: `${header("/opsr:design")}## Purpose
+      content: `${fm("Document technical decisions and architecture")}${openCodeHeader()}## Purpose
 Create a design document that captures technical decisions, architecture, trade-offs, and open questions.
 The design must be based on the proposal and spec artifacts already in the database.
 
@@ -318,7 +311,7 @@ Tell the user: "Design saved. Run \`/opsr:tasks <change-name>\` to decompose int
     {
       folder: "opsr",
       name: "tasks",
-      content: `${header("/opsr:tasks")}## Purpose
+      content: `${fm("Break a design into atomic implementation tasks")}${openCodeHeader()}## Purpose
 Decompose the specs and design into atomic, verifiable task artifacts.
 Each task must map to one or more spec requirements (REQ-NNN) and be completable in under 4 hours.
 Tasks depend on BOTH specs AND design being in the database.
@@ -361,7 +354,7 @@ Tell the user: "Tasks saved. Run \`/opsr:apply <change-name>\` to start implemen
     {
       folder: "opsr",
       name: "apply",
-      content: `${header("/opsr:apply")}## Purpose
+      content: `${fm("Implement the next pending task")}${openCodeHeader()}## Purpose
 Implement tasks one by one, validating each against the spec acceptance criteria before marking done.
 Read ALL planning artifacts (proposal, specs, design) as context before implementing any task.
 
@@ -419,7 +412,7 @@ For each acceptance criterion (REQ-NNN) in the task:
     {
       folder: "opsr",
       name: "verify",
-      content: `${header("/opsr:verify")}## Purpose
+      content: `${fm("Validate implementation against spec requirements")}${openCodeHeader()}## Purpose
 Validate the implementation against the spec requirements and design decisions.
 Produces a structured report with CRITICAL, WARNING, and SUGGESTION severity levels.
 Does NOT modify any artifacts — read-only operation.
@@ -489,7 +482,7 @@ Output a structured report:
     {
       folder: "opsr",
       name: "sync",
-      content: `${header("/opsr:sync")}## Purpose
+      content: `${fm("Merge delta specs into main specs")}${openCodeHeader()}## Purpose
 Merge delta specs (ADDED/MODIFIED/REMOVED/RENAMED sections) into the main specs stored in the database.
 Delta specs are created by /opsr:spec for MODIFIED capabilities.
 After sync, the main spec reflects all changes. This is called automatically during /opsr:archive.
@@ -548,7 +541,7 @@ Tell the user which capabilities were updated.
     {
       folder: "opsr",
       name: "archive",
-      content: `${header("/opsr:archive")}## Purpose
+      content: `${fm("Finalize and archive a completed change")}${openCodeHeader()}## Purpose
 Finalize a completed change by archiving all its artifacts.
 Runs verification checks, syncs delta specs to main specs, then archives everything.
 
@@ -596,7 +589,7 @@ Show summary:
     {
       folder: "opsr",
       name: "explore",
-      content: `${header("/opsr:explore")}## Purpose
+      content: `${fm("Investigate a problem without implementing anything")}${openCodeHeader()}## Purpose
 Think through a problem, idea, or question WITHOUT implementing anything.
 Explore creates understanding before committing to a proposal.
 You may create OpenSddRag artifacts to capture insights, but NEVER write application code.
@@ -644,7 +637,7 @@ When the user has enough insight to decide:
     {
       folder: "opsr",
       name: "continue",
-      content: `${header("/opsr:continue")}## Purpose
+      content: `${fm("Create the next artifact in the SDD dependency chain")}${openCodeHeader()}## Purpose
 Create the NEXT single artifact in the dependency chain for a change.
 Unlike /opsr:flow which creates all artifacts, this creates ONE artifact and stops.
 Dependency order: proposal → specs → design → tasks.
@@ -685,7 +678,7 @@ After creating the artifact:
     {
       folder: "opsr",
       name: "status",
-      content: `${header("/opsr:status")}## Purpose
+      content: `${fm("Show state of all in-progress changes")}${openCodeHeader()}## Purpose
 Show the current state of all in-progress changes for this project.
 Reads from the MCP server — no local files involved.
 
@@ -732,7 +725,7 @@ Then show:
     {
       folder: "opsr",
       name: "flow",
-      content: `${header("/opsr:flow")}## Purpose
+      content: `${fm("Run the complete SDD flow end-to-end")}${openCodeHeader()}## Purpose
 Run the complete SDD flow end-to-end in a single session.
 ALL artifacts are saved to the database via MCP tools — no local files.
 
@@ -785,7 +778,7 @@ Follow /opsr:archive steps:
     {
       folder: "opsr",
       name: "search",
-      content: `${header("/opsr:search")}## Purpose
+      content: `${fm("Semantic search over specs and past work")}${openCodeHeader()}## Purpose
 Search the SDD knowledge base using semantic similarity (pgvector).
 Use this BEFORE starting any new work to find existing specs, decisions, and past implementations.
 
@@ -807,6 +800,126 @@ Group by: this project / other projects / past actions.
 
 ## Step 5 — Offer to read the full artifact
 \`read_artifact(name="<artifact-name>", project_slug="${slug}")\`
+`,
+    },
+
+    // ── /opsr:harness ───────────────────────────────────────────────────────────
+    {
+      folder: "opsr",
+      name: "harness",
+      content: `${fm("Manage persistent project rules (add, list, disable)")}${openCodeHeader()}## Purpose
+Manage project harness rules: add new rules, list existing rules, and disable rules that are no longer needed.
+Harness rules are persistent behavioral constraints injected into every agent session via \`get_working_context\` (for \`trigger="always"\` rules) and surfaced as phase-gate checklists via \`get_harness_checklist\`.
+
+## Input
+$ARGUMENTS = one of:
+- \`add\` — followed by rule fields or a natural-language description
+- \`list\` — show all rules for this project
+- \`disable <rule-name>\` — soft-delete a rule by name
+
+If $ARGUMENTS is empty, show the current rules list and ask what the user wants to do.
+
+## Supported rule fields
+
+| Field | Values |
+|-------|--------|
+| \`name\`        | kebab-case slug, unique per project |
+| \`trigger\`     | \`always\` (every session) / \`on_apply\` / \`on_verify\` / \`on_archive\` / \`on_spec\` |
+| \`category\`    | \`architecture\` / \`naming\` / \`forbidden\` / \`doc-sync\` / \`verification\` |
+| \`severity\`    | \`error\` (MUST satisfy) / \`warning\` (SHOULD satisfy) / \`info\` (advisory) |
+| \`instruction\` | free-text rule the agent must follow |
+| \`metadata\`    | optional JSON |
+| \`enabled\`     | \`true\` (default) / \`false\` (soft-delete) |
+
+## Step 1 — Parse the operation
+
+If $ARGUMENTS starts with \`add\`:
+  → Go to **Step 2A — Add**
+
+If $ARGUMENTS starts with \`list\`:
+  → Go to **Step 2B — List**
+
+If $ARGUMENTS starts with \`disable <name>\`:
+  → Go to **Step 2C — Disable**
+
+If $ARGUMENTS is empty:
+  → Call \`list_rules(project_slug="${slug}")\` and show the current state. Ask the user what they want to do.
+
+## Step 2A — Add a rule
+
+If the user provided explicit fields after \`add\`, use them as-is.
+
+Otherwise, ask the user for each field. **You can infer sensible defaults from natural language:**
+- "always update CHANGELOG when applying" → trigger=\`on_apply\`, category=\`doc-sync\`, severity=\`warning\`
+- "never do X" → trigger=\`always\`, category=\`forbidden\`, severity=\`error\`
+- "use Y pattern" → trigger=\`always\`, category=\`architecture\`, severity=\`warning\`
+
+**Show the inferred values and ask for confirmation** before calling \`add_rule\`.
+
+Then call:
+\`\`\`
+add_rule(
+  name:        "<kebab-case>",
+  trigger:     "<always|on_apply|on_verify|on_archive|on_spec>",
+  category:    "<architecture|naming|forbidden|doc-sync|verification>",
+  severity:    "<error|warning|info>",
+  instruction: "<text>",
+  project_slug:"${slug}",
+  enabled:     true
+)
+\`\`\`
+
+Confirm to the user:
+"Rule '<name>' added. It will [be injected into every working context | be checked during /opsr:<trigger> when the phase completes]."
+
+Then record:
+\`record_trace(action="add_rule", result_summary="Added harness rule: <name>", project_slug="${slug}")\`
+
+## Step 2B — List rules
+
+Call:
+\`list_rules(project_slug="${slug}", enabled_only=true)\`
+
+Present the results **grouped by trigger**, in this order:
+
+\`\`\`
+### Always (loaded at session start)
+- [<category>:<severity>] <name> — <instruction (max 80 chars)>
+
+### On Apply (checked during /opsr:apply)
+- ...
+
+### On Verify (checked during /opsr:verify)
+- ...
+
+### On Archive (checked during /opsr:archive)
+- ...
+
+### On Spec (checked during /opsr:spec)
+- ...
+\`\`\`
+
+If the result list is empty, respond:
+"No harness rules defined for this project. Run \`/opsr:harness add\` to create the first rule."
+
+## Step 2C — Disable a rule
+
+Extract the rule name from $ARGUMENTS (the token after \`disable\`).
+
+Call:
+\`add_rule(name: "<name>", enabled: false, project_slug: "${slug}")\`
+
+Confirm:
+"Rule '<name>' disabled. It will no longer appear in checklists or session context. Re-add with the same name to re-enable."
+
+Then record:
+\`record_trace(action="disable_rule", result_summary="Disabled harness rule: <name>", project_slug="${slug}")\`
+
+## Notes
+
+- The same \`add_rule\` MCP call is used for create, update, and soft-delete — it is idempotent on \`(project_id, name)\`.
+- Disabled rules are preserved in the database and can be re-enabled by calling \`add_rule\` with the same \`name\` and \`enabled=true\`.
+- Rules are project-scoped — they never leak across projects.
 `,
     },
   ];

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