opensddrag 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,236 @@
+# opensddrag
+
+CLI client to connect any project to the [OpenSddRag](https://github.com/conexaoelite/OpenSddRag) SDD+Harness MCP server.
+
+OpenSddRag implements **Spec-Driven Development (SDD)** — a structured workflow where every feature flows through `propose → spec → design → tasks → apply → archive`, backed by a PostgreSQL/pgvector semantic memory store. This CLI wires your project's AI tools to that server in seconds.
+
+## Prerequisites
+
+- Node.js ≥ 18
+- A running OpenSddRag MCP server (see [server setup](#server-setup))
+
+## Installation
+
+```bash
+# one-off, no install needed
+npx opensddrag init
+
+# or install globally
+npm install -g opensddrag
+opensddrag init
+```
+
+## Quick Start
+
+```bash
+# 1. Start the OpenSddRag server (Docker)
+docker compose up -d          # runs on http://localhost:8000
+
+# 2. Inside your project, connect it
+cd my-project
+npx opensddrag init
+
+# 3. Open the project in Claude Code — the MCP server is ready
+```
+
+The `init` command registers your project on the server, writes MCP config files, installs SDD slash commands, and appends a section to `CLAUDE.md`.
+
+## Commands
+
+### `opensddrag init`
+
+Connect the current directory to an OpenSddRag MCP server.
+
+```
+Options:
+  --server <url>      Server URL  (default: http://localhost:8000)
+  --project <slug>    Project slug  (default: directory name)
+  --name <name>       Project display name
+  --api-key <key>     API key for password-protected servers
+  --tools <list>      AI tools to configure: claude, opencode  (default: ask)
+  --yes               Skip all confirmation prompts
+```
+
+**Examples**
+
+```bash
+# Interactive — prompts for all values
+npx opensddrag init
+
+# Non-interactive — CI / scripted setup
+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
+```
+
+**What gets created in your project**
+
+| Path | Purpose |
+|---|---|
+| `.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) |
+| `opensddrag.yaml` | Local project marker (`project` + `server`) |
+
+---
+
+### `opensddrag status`
+
+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:
+- `opensddrag.yaml` — local config found
+- Skills — how many of the 13 expected skill files are present
+- `.mcp.json` / `opencode.json` — MCP server entry
+- Slash commands — which `/opsr:*` commands are installed
+- `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:`):
+
+| Command | When to use |
+|---|---|
+| `/opsr:propose` | Capture intent and scope — start here |
+| `/opsr:spec` | Formalize requirements (Purpose / SHALL / Scenarios) |
+| `/opsr:design` | Document technical decisions and trade-offs |
+| `/opsr:tasks` | Break a spec into atomic tasks (< 4 h each) |
+| `/opsr:apply` | Implement the next pending task against spec criteria |
+| `/opsr:verify` | Confirm a task is done and acceptance criteria are met |
+| `/opsr:sync` | Merge delta specs after mid-flight design changes |
+| `/opsr:archive` | Mark a completed feature as archived |
+| `/opsr:explore` | Explore and investigate before committing to a plan |
+| `/opsr:continue` | Resume the last in-progress artifact |
+| `/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
+
+The MCP server is a separate Python package (`opensddrag` on PyPI) that requires PostgreSQL with the pgvector extension.
+
+**Docker (recommended)**
+
+```bash
+# Clone the repo or copy docker-compose.yml
+git clone https://github.com/conexaoelite/OpenSddRag
+cd OpenSddRag
+docker compose up -d
+```
+
+The server starts on `http://localhost:8000`. The database runs on `localhost:54326`.
+
+**Local (development)**
+
+```bash
+cd mcp-server
+cp .env.example .env
+uv pip install -e .
+opensddrag init          # run migrations + seed global SDD skills
+opensddrag server start --transport sse --port 8000
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensddrag",
-  "version": "0.1.0",
+  "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;
+}