opensddrag 0.1.1 → 0.1.2

package/README.md

@@ -63,6 +63,9 @@ npx opensddrag init --server http://localhost:8000 --project my-app --yes
 # Remote server with an API key
 npx opensddrag init --server https://sdd.example.com --api-key sk-... --yes
 
+# CI — configure via env vars, no flags needed
+OPENSDDRAG_SERVER_URL=http://mcp.internal:8000 OPENSDDRAG_API_KEY=sk-... npx opensddrag init --project my-app --yes
+
 # Configure only OpenCode (skip Claude Code)
 npx opensddrag init --tools opencode
 ```
@@ -74,8 +77,11 @@ npx opensddrag init --tools opencode
 | `.mcp.json` | Claude Code MCP server entry (`type: http`) |
 | `opencode.json` | OpenCode MCP server entry (only with `--tools opencode`) |
 | `.claude/skills/opensddrag-*/SKILL.md` | One skill file per SDD command |
+| `.claude/skills/opensddrag-harness/SKILL.md` | Harness rule management skill |
 | `.agents/skills/opensddrag-*/SKILL.md` | Same skills for agent-native tooling |
+| `.agents/skills/opensddrag-harness/SKILL.md` | Same harness skill for agent-native tooling |
 | `.opencode/skills/opensddrag-*/SKILL.md` | OpenCode-native skills (when selected) |
+| `.opencode/skills/opensddrag-harness/SKILL.md` | OpenCode-native harness skill (when selected) |
 | `.claude/commands/opsr/*.md` | Claude Code slash commands |
 | `.opencode/commands/opsr/*.md` | OpenCode slash commands (when selected) |
 | `CLAUDE.md` | OpenSddRag section appended (or file created) |
@@ -87,8 +93,14 @@ npx opensddrag init --tools opencode
 
 Check whether the current project is correctly wired to the server.
 
+```
+Options:
+  --server <url>   Override the server URL for this check
+```
+
 ```bash
 npx opensddrag status
+npx opensddrag status --server http://mcp.internal:8000
 ```
 
 Reports:
@@ -99,6 +111,32 @@ Reports:
 - `CLAUDE.md` — whether the OpenSddRag section exists
 - Server — live health check + project registration confirmation
 
+## Environment Variables
+
+Both `init` and `status` support configuration via environment variables. Precedence order (first match wins):
+
+1. `--server` / `--api-key` CLI flags
+2. Environment variables
+3. `opensddrag.yaml` (`server_url` or `server` field)
+4. Built-in default (`http://localhost:8000`)
+
+| Variable | Purpose |
+|---|---|
+| `OPENSDDRAG_SERVER_URL` | MCP server URL — used when no `--server` flag is passed |
+| `OPENSDDRAG_API_KEY` | API key for authenticated servers — used when no `--api-key` flag is passed |
+
+```bash
+# Connect to a remote server without flags
+export OPENSDDRAG_SERVER_URL=http://mcp.internal:8000
+export OPENSDDRAG_API_KEY=sk-abc123
+npx opensddrag init --project my-app --yes
+npx opensddrag status
+```
+
+`OPENSDDRAG_API_KEY` is honored for any server URL — including `localhost` — so local servers with `AUTH_ENABLED=true` work correctly.
+
+---
+
 ## SDD Slash Commands
 
 After `init`, the following slash commands are available inside Claude Code (prefix `/opsr:`):
@@ -118,6 +156,55 @@ After `init`, the following slash commands are available inside Claude Code (pre
 | `/opsr:status` | Show what is in progress and what is done |
 | `/opsr:flow` | Run the full SDD flow end-to-end for a feature |
 | `/opsr:search` | Semantic search over specs and past work |
+| `/opsr:harness` | Add, list, or disable project rules enforced at SDD phase gates |
+
+## Harness
+
+The Harness is a rule-gate layer built on top of the SDD workflow. It lets you define persistent, per-project behavioral rules that are automatically injected into every agent session and enforced at specific SDD phase gates.
+
+**How it works:**
+- Rules are stored in the MCP server's database, scoped to your project.
+- `always` rules are returned automatically by `get_working_context` at the start of every session.
+- Phase-gate rules (`on_spec`, `on_apply`, `on_verify`, `on_archive`) are surfaced by `get_harness_checklist` when the corresponding SDD command runs its gate step.
+- Agents check the checklist before completing each gate action and must satisfy all `error`-severity rules.
+
+### Triggers
+
+| Trigger | When it fires |
+|---|---|
+| `always` | Every agent session — injected via `get_working_context` |
+| `on_spec` | Before saving a spec artifact (`/opsr:spec`) |
+| `on_apply` | Before marking a task complete (`/opsr:apply`) |
+| `on_verify` | Before declaring verification done (`/opsr:verify`) |
+| `on_archive` | Before archiving change artifacts (`/opsr:archive`) |
+
+### MCP Tools
+
+| Tool | Description |
+|---|---|
+| `add_rule` | Create or update a project rule (name, trigger, category, severity, instruction) |
+| `list_rules` | List all rules for the project, grouped by trigger |
+| `get_harness_checklist` | Return enabled rules for a specific trigger — called by SDD commands at phase gates |
+
+### Managing rules
+
+```bash
+# Inside Claude Code, after opensddrag init:
+
+# Add a rule interactively
+/opsr:harness add
+
+# Add a rule directly
+/opsr:harness add name=no-raw-sql trigger=on_apply category=forbidden severity=error instruction="Never write raw SQL strings — use the repository layer"
+
+# List all rules
+/opsr:harness list
+
+# Disable a rule
+/opsr:harness disable no-raw-sql
+```
+
+---
 
 ## Server Setup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensddrag",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI client to connect any project to the OpenSddRag SDD+Harness MCP server",
   "keywords": [
     "sdd",

package/src/commands/init.js

@@ -5,10 +5,12 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join, basename } from "path";
 
 import { checkHealth, createProject } from "../api.js";
+import { DEFAULT_SERVER_URL, resolveServerUrl, resolveApiKey } from "../config.js";
 import { renderClaudeMdBlock, renderClaudeMdStandalone } from "../templates/claude-md.js";
 import { getCommands } from "../templates/commands/index.js";
 import { getOpenCodeCommands } from "../templates/commands/opencode.js";
-import { getSkills } from "../templates/skills/index.js";
+import { getSkills, getOpenCodeSkills } from "../templates/skills/index.js";
+import { getHarnessSkill, getOpenCodeHarnessSkill } from "../templates/skill-md.js";
 
 // ── Config writers ─────────────────────────────────────────────────────────────
 
@@ -40,6 +42,9 @@ function writeOpenCode(cwd, serverUrl, _apiKey) {
     url: `${serverUrl}/mcp`,
     enabled: true,
   };
+  if (_apiKey) {
+    config.mcp.opensddrag.headers = { Authorization: `Bearer ${_apiKey}` };
+  }
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
   return "opencode.json";
 }
@@ -55,7 +60,7 @@ export const initCommand = new Command("init")
   .description("Connect the current project to an OpenSddRag MCP server")
   .option("--project <slug>", "Project slug (default: current directory name)")
   .option("--name <name>", "Project display name")
-  .option("--server <url>", "OpenSddRag server URL", "http://localhost:8000")
+  .option("--server <url>", "OpenSddRag server URL")
   .option("--api-key <key>", "API key for authenticated servers")
   .option("--tools <list>", "Comma-separated tools to configure: claude,opencode (default: ask)")
   .option("--yes", "Skip confirmation prompts")
@@ -65,13 +70,16 @@ export const initCommand = new Command("init")
     console.log(chalk.bold("\n  OpenSddRag — Project Init\n"));
 
     // ── Inputs ────────────────────────────────────────────────────────────────
-    const serverUrl = opts.server ||
-      await input({ message: "OpenSddRag server URL:", default: "http://localhost:8000" });
+    const resolvedUrl = resolveServerUrl(opts, cwd);
+    let serverUrl;
+    if (opts.yes || resolvedUrl !== DEFAULT_SERVER_URL) {
+      serverUrl = resolvedUrl;
+    } else {
+      serverUrl = await input({ message: "OpenSddRag server URL:", default: DEFAULT_SERVER_URL });
+    }
 
-    // Prompt for API key when connecting to a remote server
-    const isRemote = !serverUrl.includes("localhost") && !serverUrl.includes("127.0.0.1");
-    let apiKey = opts.apiKey || null;
-    if (!apiKey && isRemote && !opts.yes) {
+    let apiKey = resolveApiKey(opts);
+    if (!apiKey && !opts.yes) {
       apiKey = await password({
         message: "API key (leave blank to skip — server must have AUTH_ENABLED=false):",
         mask: "*",
@@ -114,15 +122,15 @@ export const initCommand = new Command("init")
     console.log("\n" + chalk.dim("  Will create/update:"));
     if (selectedTools.includes("Claude Code")) {
       console.log(chalk.dim("    .mcp.json                                    — MCP server (type: http)"));
+      console.log(chalk.dim("    .claude/skills/opensddrag-*/SKILL.md         — individual skill per command"));
+      console.log(chalk.dim("    .agents/skills/opensddrag-*/SKILL.md         — individual skill per command"));
+      console.log(chalk.dim("    .claude/commands/opsr/       — slash commands (/opsr:propose, /opsr:apply, /opsr:harness...)"));
     }
-    console.log(chalk.dim("    .claude/skills/opensddrag-*/SKILL.md         — individual skill per command"));
-    console.log(chalk.dim("    .agents/skills/opensddrag-*/SKILL.md         — individual skill per command"));
     if (selectedTools.includes("OpenCode")) {
-      console.log(chalk.dim("    opencode.json               — MCP server"));
+      console.log(chalk.dim("    opencode.json                — MCP server"));
       console.log(chalk.dim("    .opencode/skills/opensddrag-*/SKILL.md     — OpenCode-native skills"));
-      console.log(chalk.dim("    .opencode/commands/opsr/    — slash commands (/opsr:propose, /opsr:apply...)"));
+      console.log(chalk.dim("    .opencode/commands/opsr/     — slash commands (/opsr:propose, /opsr:apply...)"));
     }
-    console.log(chalk.dim("    .claude/commands/opsr/        — slash commands (/opsr:propose, /opsr:apply...)"));
     console.log(chalk.dim("    CLAUDE.md                    — OpenSddRag section"));
     console.log(chalk.dim(`    Remote: register '${slug}' in central database\n`));
 
@@ -138,9 +146,13 @@ export const initCommand = new Command("init")
       console.log(chalk.green("✓"));
     } catch {
       console.log(chalk.red("✗"));
+      const isLocal = serverUrl.includes("localhost") || serverUrl.includes("127.0.0.1");
       console.error(chalk.red(`\n  Cannot reach ${serverUrl}`));
-      console.error(chalk.dim("  Make sure the OpenSddRag server is running:"));
-      console.error(chalk.dim("    docker compose up -d"));
+      if (isLocal) {
+        console.error(chalk.dim("  Make sure the OpenSddRag server is running:"));
+        console.error(chalk.dim("    docker compose up -d"));
+      }
+      console.error(chalk.dim("  Pass --server <url> or set OPENSDDRAG_SERVER_URL."));
       process.exit(1);
     }
 
@@ -165,57 +177,60 @@ export const initCommand = new Command("init")
       const file = TOOL_WRITERS[tool](cwd, serverUrl, apiKey);
       configured.push(`${tool} → ${file}`);
     }
-    // Individual skill files per command
-    const skills = getSkills(slug, serverUrl);
-    const skillRoots = [
-      join(cwd, ".claude", "skills"),
-      join(cwd, ".agents", "skills"),
-    ];
-    for (const skill of skills) {
-      for (const root of skillRoots) {
-        const skillDir = join(root, skill.name);
-        mkdirSync(skillDir, { recursive: true });
-        writeFileSync(join(skillDir, "SKILL.md"), skill.content);
+    // Individual skill files per command — each tool gets its own generator
+    if (selectedTools.includes("Claude Code")) {
+      const ccSkills = [
+        ...getSkills(slug, serverUrl),
+        { name: "opensddrag-harness", content: getHarnessSkill({ slug, serverUrl }) },
+      ];
+      const ccRoots = [join(cwd, ".claude", "skills"), join(cwd, ".agents", "skills")];
+      for (const skill of ccSkills) {
+        for (const root of ccRoots) {
+          const skillDir = join(root, skill.name);
+          mkdirSync(skillDir, { recursive: true });
+          writeFileSync(join(skillDir, "SKILL.md"), skill.content);
+        }
+        configured.push(`skill → ${skill.name}/SKILL.md (${ccRoots.length} root(s))`);
       }
-      configured.push(`skill → .claude/skills/${skill.name}/SKILL.md`);
     }
-
-    // Install OpenCode-native skills if OpenCode is selected
     if (selectedTools.includes("OpenCode")) {
-      const opencodeSkillsRoot = join(cwd, ".opencode", "skills");
-      for (const skill of skills) {
-        const skillDir = join(opencodeSkillsRoot, skill.name);
+      const ocSkills = [
+        ...getOpenCodeSkills(slug, serverUrl),
+        { name: "opensddrag-harness", content: getOpenCodeHarnessSkill({ slug, serverUrl }) },
+      ];
+      const ocRoot = join(cwd, ".opencode", "skills");
+      for (const skill of ocSkills) {
+        const skillDir = join(ocRoot, skill.name);
         mkdirSync(skillDir, { recursive: true });
         writeFileSync(join(skillDir, "SKILL.md"), skill.content);
-        configured.push(`skill → .opencode/skills/${skill.name}/SKILL.md`);
+        configured.push(`skill → ${skill.name}/SKILL.md (1 root(s))`);
       }
     }
     console.log(chalk.green("✓"));
     for (const c of configured) console.log(chalk.dim(`    ${c}`));
 
-    // ── 4. Slash commands (.claude/commands/opsr/) ───────────────────────────
+    // ── 4. Slash commands ────────────────────────────────────────────────────
     process.stdout.write(chalk.bold("  4/5 ") + "Writing slash commands... ");
-    const commands = getCommands(slug, serverUrl);
-    for (const cmd of commands) {
-      const cmdDir = join(cwd, ".claude", "commands", cmd.folder);
-      mkdirSync(cmdDir, { recursive: true });
-      writeFileSync(join(cmdDir, `${cmd.name}.md`), cmd.content);
-    }
-    console.log(chalk.green(`✓ (${commands.length} commands)`));
-    for (const cmd of commands) {
-      console.log(chalk.dim(`    /${cmd.folder}:${cmd.name}`));
+    let totalCommands = 0;
+    if (selectedTools.includes("Claude Code")) {
+      const commands = getCommands(slug, serverUrl);
+      for (const cmd of commands) {
+        const cmdDir = join(cwd, ".claude", "commands", cmd.folder);
+        mkdirSync(cmdDir, { recursive: true });
+        writeFileSync(join(cmdDir, `${cmd.name}.md`), cmd.content);
+      }
+      totalCommands += commands.length;
     }
-
-    // Install OpenCode-native commands if OpenCode is selected
     if (selectedTools.includes("OpenCode")) {
       const opencodeCommands = getOpenCodeCommands(slug, serverUrl);
       for (const cmd of opencodeCommands) {
         const cmdDir = join(cwd, ".opencode", "commands", cmd.folder);
         mkdirSync(cmdDir, { recursive: true });
         writeFileSync(join(cmdDir, `${cmd.name}.md`), cmd.content);
-        configured.push(`command → .opencode/commands/${cmd.folder}/${cmd.name}.md`);
       }
+      totalCommands += opencodeCommands.length;
     }
+    console.log(chalk.green(`✓ (${totalCommands} commands)`));
 
     // ── 5. CLAUDE.md ──────────────────────────────────────────────────────────
     process.stdout.write(chalk.bold("  5/5 ") + "Updating CLAUDE.md... ");

package/src/commands/status.js

@@ -4,25 +4,22 @@ import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 
 import { checkHealth, listProjects } from "../api.js";
+import { resolveServerUrl, loadOpensddragYaml } from "../config.js";
 
 export const statusCommand = new Command("status")
   .description("Check OpenSddRag connection status for the current project")
-  .action(async () => {
+  .option("--server <url>", "OpenSddRag server URL")
+  .action(async (opts) => {
     const cwd = process.cwd();
 
     console.log(chalk.bold("\n  OpenSddRag — Status\n"));
 
-    let serverUrl = "http://localhost:8000";
-    let slug = null;
+    const serverUrl = resolveServerUrl(opts, cwd);
+    const yaml = loadOpensddragYaml(cwd);
+    const slug = yaml?.project ?? null;
 
     // ── Local config ──────────────────────────────────────────────────────────
-    const yamlPath = join(cwd, "opensddrag.yaml");
-    if (existsSync(yamlPath)) {
-      const yaml = readFileSync(yamlPath, "utf8");
-      const slugMatch = yaml.match(/^project:\s*(.+)$/m);
-      const serverMatch = yaml.match(/^server:\s*(.+)$/m);
-      if (slugMatch) slug = slugMatch[1].trim();
-      if (serverMatch) serverUrl = serverMatch[1].trim();
+    if (yaml) {
       console.log(chalk.green("  ✓") + ` opensddrag.yaml  →  project: ${chalk.cyan(slug)}`);
     } else {
       console.log(chalk.red("  ✗") + " opensddrag.yaml not found — run: " + chalk.dim("opensddrag init"));

package/src/config.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+export const DEFAULT_SERVER_URL = "http://localhost:8000";
+
+/**
+ * Parse opensddrag.yaml from cwd.
+ * Reads both `server:` and `server_url:` keys for backward compatibility.
+ * Returns { project, server_url } or null on missing/malformed file.
+ */
+export function loadOpensddragYaml(cwd) {
+  const yamlPath = join(cwd, "opensddrag.yaml");
+  if (!existsSync(yamlPath)) return null;
+  try {
+    const text = readFileSync(yamlPath, "utf8");
+    const projectMatch = text.match(/^project:\s*["']?(.+?)["']?\s*$/m);
+    const serverMatch = text.match(/^(?:server_url|server):\s*["']?(.+?)["']?\s*$/m);
+    return {
+      project: projectMatch?.[1]?.trim() ?? null,
+      server_url: serverMatch?.[1]?.trim() ?? null,
+    };
+  } catch {
+    process.stderr.write("Warning: Ignoring malformed opensddrag.yaml\n");
+    return null;
+  }
+}
+
+/**
+ * Resolve the MCP server URL with precedence:
+ *   1. opts.server  (--server CLI flag)
+ *   2. OPENSDDRAG_SERVER_URL env var
+ *   3. opensddrag.yaml server_url / server field
+ *   4. DEFAULT_SERVER_URL
+ */
+export function resolveServerUrl(opts, cwd) {
+  if (opts?.server) return opts.server;
+  if (process.env.OPENSDDRAG_SERVER_URL) return process.env.OPENSDDRAG_SERVER_URL;
+  const yaml = loadOpensddragYaml(cwd ?? process.cwd());
+  if (yaml?.server_url) return yaml.server_url;
+  return DEFAULT_SERVER_URL;
+}
+
+/**
+ * Resolve the API key with precedence:
+ *   1. opts.apiKey  (--api-key CLI flag)
+ *   2. OPENSDDRAG_API_KEY env var
+ *   3. null
+ */
+export function resolveApiKey(opts) {
+  if (opts?.apiKey) return opts.apiKey;
+  if (process.env.OPENSDDRAG_API_KEY) return process.env.OPENSDDRAG_API_KEY;
+  return null;
+}

package/src/templates/commands/index.js

@@ -6,7 +6,8 @@ export function getCommands(slug, serverUrl) {
    */
   const artifactHeader = (name) => `> **IMPORTANT — ${name}**
 > This command requires the **\`opensddrag\`** MCP server (${serverUrl}), configured in \`.mcp.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\`
+> 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\`, \`get_harness_checklist\`
+
 > **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}\`**
@@ -22,12 +23,67 @@ export function getCommands(slug, serverUrl) {
    */
   const implementHeader = (name) => `> **IMPORTANT — ${name}**
 > This command requires the **\`opensddrag\`** MCP server (${serverUrl}), configured in \`.mcp.json\`.
-> MCP tools provided by this server: \`read_artifact\`, \`list_artifacts\`, \`update_artifact\`, \`get_relationships\`, \`search_semantic\`, \`recall_episodes\`, \`get_working_context\`, \`update_working_context\`, \`record_trace\`
+> MCP tools provided by this server: \`read_artifact\`, \`list_artifacts\`, \`update_artifact\`, \`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**: 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."
 > SDD planning artifacts are read/traced via these MCP tools. Code implementation writes local files using Edit, Write, Bash — this is expected and required.
 > **project_slug for every MCP call: \`${slug}\`**
 
 ---
+`;
+
+  /**
+   * Header for harness-management commands (harness).
+   * Project rules are stored in the MCP server's project_rules table.
+   * No local file writes — all persistence is via the harness MCP tools.
+   */
+  const harnessHeader = (name) => `> **IMPORTANT — ${name}**
+> This command requires the **\`opensddrag\`** MCP server (${serverUrl}), configured in \`.mcp.json\`.
+> MCP tools provided by this server: \`add_rule\`, \`list_rules\`, \`get_harness_checklist\`, \`get_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."
+> Harness rules are persisted in the MCP server's database. Do NOT write rule definitions to local files.
+> **project_slug for every call: \`${slug}\`**
+
+---
+`;
+
+  /**
+   * Reusable step block that calls `get_harness_checklist(trigger=...)` and
+   * presents the results as a phase-gate checklist. Injected into `/opsr:apply`,
+   * `/opsr:verify`, `/opsr:archive`, and `/opsr:spec` per spec
+   * `harness-engineering-harness-checklist-spec` (REQ-002, REQ-003).
+   *
+   * Behavior:
+   * - If the checklist is empty, print "No harness rules for this trigger." and
+   *   continue normally.
+   * - If the checklist has error-severity rules, the agent MUST confirm each
+   *   one is satisfied before proceeding to the next step.
+   * - Warning-severity rules are presented as advisory (SHOULD complete).
+   *
+   * @param {string} trigger - One of: "on_apply", "on_verify", "on_archive", "on_spec"
+   * @param {string} gateLabel - Short human-readable label for the gate, e.g. "Marking task archived"
+   * @returns {string} Markdown step content
+   */
+  const harnessChecklistStep = (trigger, gateLabel) => `## Step — Harness checklist (${trigger})
+Call MCP tool to load all enabled harness rules for the \`${trigger}\` trigger:
+\`get_harness_checklist(trigger="${trigger}", project_slug="${slug}")\`
+
+Process the response as follows:
+- **If the result is an empty array \`[]\`** → output "No harness rules for this trigger." and continue to the next step.
+- **If any rule has \`severity="error"\`** → present it as:
+  \`\`\`
+  MUST complete before proceeding (${gateLabel}):
+  - [<name>] <instruction>
+  \`\`\`
+  Then \`STOP\` and wait for the agent/user to confirm each error-severity rule has been satisfied before continuing.
+- **If any rule has \`severity="warning"\`** → present it as:
+  \`\`\`
+  SHOULD complete:
+  - [<name>] <instruction>
+  \`\`\`
+  These are advisory; proceed if the agent judges them satisfied, otherwise complete them first.
+- **If any rule has \`severity="info"\`** → present it inline as "Info: [<name>] <instruction>"; proceed normally.
+- Rules are returned sorted error-first then by name; preserve that order when displaying.
+- This step must run BEFORE the next phase-gate step (archiving the task, finalizing verification, archiving change artifacts, or saving the spec to the database).
 
 `;
 
@@ -242,6 +298,7 @@ If no main spec → create BOTH:
 - TO: \`### Requirement: New Name\`
 \`\`\`
 
+${harnessChecklistStep("on_spec", "Saving specs to the database")}
 ## Step 4 — Save each spec to the database
 For each capability spec:
 \`create_artifact(name="<change-name>-<capability-name>-spec", type="spec", content="<full spec markdown>", metadata={"change_name": "<change-name>", "capability": "<capability-name>", "is_delta": true/false}, project_slug="${slug}")\`
@@ -425,6 +482,7 @@ For each acceptance criterion (REQ-NNN) in the task:
 - Confirm the implementation satisfies the requirement
 - Verify no spec scenarios are broken
 
+${harnessChecklistStep("on_apply", "Marking task archived")}
 ## Step 7 — Mark task as done in database
 \`update_artifact(name="<task-name>", status="archived", project_slug="${slug}")\`
 
@@ -475,6 +533,7 @@ For each decision:
 - Check if the implementation follows the chosen approach
 - If implementation deviates from a decision → **SUGGESTION: Possible deviation from design**
 
+${harnessChecklistStep("on_verify", "Declaring verification complete")}
 ## Step 5 — Generate report
 Output a structured report:
 
@@ -600,6 +659,7 @@ If delta specs exist:
 - If yes → execute <opsr:sync logic for each delta spec
 - If no → archive without syncing
 
+${harnessChecklistStep("on_archive", "Archiving change artifacts")}
 ## Step 5 — Archive all change artifacts
 For each artifact in this change (proposal, all specs, design, all tasks):
 \`update_artifact(name="<artifact-name>", status="archived", metadata={"archived_at": "<ISO timestamp>", "change_name": "<change-name>"}, project_slug="${slug}")\`
@@ -831,6 +891,134 @@ 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: `${harnessHeader("/opsr:harness")}## 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\` (e.g. \`add name=repo-pattern trigger=always category=architecture severity=error instruction="..."\`), 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 the operation:
+\`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> — <truncated 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."
+
+If rules exist in only some sections, show "(none)" for empty sections.
+
+## 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}")\`
+
+(You don't need to pass the other fields — \`add_rule\` is an upsert keyed on \`(project_id, name)\` and will set the existing rule's \`enabled\` flag to \`false\`.)
+
+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.
+- The OpenCode equivalent of this command is the \`opensddrag-harness\` skill, which calls the same MCP tools.
 `,
     },
   ];