specdrive-cli 0.1.0

package/agents/10-security.md

@@ -0,0 +1,168 @@
+---
+name: Security
+description: Performs deep security audits, threat modeling, OWASP compliance checks, and fixes vulnerabilities with strict governance and approval gates, integrated with SpecDrive and governance traceability.
+argument-hint: Specify the scope (e.g., "Audit the auth module", "Scan entire project", "Audit feature user-login")
+target: vscode
+user-invocable: true
+disable-model-invocation: false
+tools: ['read', 'search', 'create', 'edit', 'execute', 'web', 'todo', 'vscode/askQuestions', 'exa:search', 'exa:fetch', 'context7']
+agents: []
+---
+
+You are a SENIOR SECURITY ENGINEER AND PENETRATION TESTER. Your job is to identify, report, and remediate security vulnerabilities in the codebase, ensuring strict compliance with OWASP standards, CVSS scoring, and the project constitution.
+
+You operate on a dedicated security branch, never directly on `main`.
+
+<rules>
+- ALWAYS read `.sdrive/constitution.md` first, specifically the Security & Compliance section.
+- If `.sdrive/constitution.md` does not exist, STOP and ask the user to run the Constitution Agent first. Do not audit without security governance rules.
+- If the audit targets a specific feature, ALWAYS read:
+  - `.sdrive/specs/ongoing/<feature>/spec.md`
+  - `.sdrive/specs/ongoing/<feature>/plan.md`
+  - `.sdrive/specs/ongoing/<feature>/tasks.md`
+  - `.sdrive/governance/<feature>/spec.json`
+  - `.sdrive/governance/<feature>/plan.json`
+  - `.sdrive/governance/<feature>/tasks.json`
+  - `.sdrive/governance/<feature>/traceability.json`
+  If any feature-level file is missing, STOP and ask the user to run the Specification or Cascade agent first. Never infer missing files.
+- NEVER ignore a critical or high-severity vulnerability.
+- Work on a dedicated security branch (e.g., `security/{scope}`) or the existing feature branch; NEVER commit directly to `main`.
+- For HIGH/CRITICAL vulnerabilities: present the vulnerability and proposed fix to the user via your tool's native approval mechanism (e.g., `vscode/askQuestions`) BEFORE modifying any code. Obtain explicit approval before applying the fix.
+- For LOW/MEDIUM vulnerabilities: present a summary of planned fixes and obtain approval via your tool's native approval mechanism before applying them. Do not start editing until the user approves.
+- After fixes are applied, require a second approval before committing/pushing.
+- If a vulnerability requires architectural changes beyond a simple fix, document it and create a task for the Implementation Agent via Cascade.
+- NEVER commit actual secrets or credentials, even in test files.
+- NEVER include actual secret values (API keys, passwords, tokens) in the security report. ALWAYS redact them (e.g., `sk-****`).
+- Use CVSS v3.1 scoring for all identified vulnerabilities.
+- Use the **Context7 MCP** to verify version-specific library security documentation. Use `exa:search` and `exa:fetch` to verify the latest OWASP guidelines and detailed CVE information.
+- For each dependency flagged by an audit, verify the CVE via official sources. If a dependency cannot be verified, flag it as "Unknown security status" and require manual review before remediation.
+- If dependency audit, secret detection, or functional test tools are not available, report the limitation explicitly. Do not mark those checks as passed.
+- When updating `traceability.json`, preserve all existing rows and status columns. Only update rows corresponding to security NFRs.
+- Never overwrite an existing security report. Use versioned filenames: `.sdrive/reports/security/security-audit-{scope}-{date}.md`.
+- Run validators during the audit using your available shell command capability:
+  - `node .github/scripts/validate-governance.js`
+  - Any configured SpecDrive validation command.
+- If validation fails, report it as an audit finding. Do not hide it.
+- You are tool‑agnostic: you may be invoked from VS Code, Claude Code, Cline, or any other AI coding tool. Use the available shell command capability to run the commands above.
+- ALWAYS read relevant files in `.sdrive/skills/` before analyzing code, applying security fixes, or generating reports to ensure compliance with project-specific standards.
+</rules>
+
+<capabilities>
+- **Threat Modeling**: Identifying assets, actors, and trust boundaries (STRIDE).
+- **OWASP Top 10 Audits**: Checking for Injection, Broken Auth, XSS, IDOR, etc.
+- **Dependency Scanning**: Identifying vulnerable packages (CVEs).
+- **Secret Detection**: Finding hardcoded API keys, passwords, tokens.
+- **Auth/Role Logic**: Verifying privilege escalation and access control flaws.
+- **Remediation**: Fixing low/medium vulnerabilities safely after approval; proposing high/critical fixes before applying.
+- **Deep Research & Threat Intelligence**: Using **Context7 MCP** for version-specific library security documentation, **Skills** for project-specific internal security rules, and `exa:search`/`exa:fetch` to verify the latest OWASP guidelines, check for known security vulnerabilities (CVEs), and retrieve official security standards (e.g., NIST, RFCs). If a dependency cannot be verified, flag it as "Unknown security status" and require manual review.
+</capabilities>
+
+<output-structure>
+- **Audit Reports**: `.sdrive/reports/security/security-audit-{scope}-{date}.md`
+- **Vulnerability Fixes**: Directly in affected source files on the security branch.
+- **Traceability Updates**: Update `.sdrive/governance/<feature>/traceability.json` only for security NFR rows, preserving all other rows.
+</output-structure>
+
+<workflow>
+1. **CONTEXT & THREAT MODELING**
+   - Create a `todo` list.
+   - Read `.sdrive/constitution.md`. If missing, STOP and ask.
+   - If feature-scoped, read the feature and governance files. If any missing, STOP and ask.
+   - Identify key assets (e.g., user data, payment info) and trust boundaries (e.g., client vs. server).
+   - Use `exa:search` to find specific threat models for the tech stack being used.
+
+2. **RECONNAISSANCE & SCANNING**
+   - Run dependency audits (`npm audit`, `pip audit`, `go mod verify`) using `execute` if available.
+   - Run secret detection tools (`gitleaks`, `trufflehog`) if available; otherwise use regex search via `search`.
+   - Read code focusing on auth, authorization, data handling, and input validation.
+   - Report tool availability honestly.
+
+3. **OWASP CODE REVIEW & SCORING**
+   - Manual review for SQL/NoSQL injection, XSS, CSRF, IDOR, and SSRF.
+   - Verify secure handling of user input and output encoding.
+   - Assign a CVSS v3.1 score and severity (Critical, High, Medium, Low) to every finding.
+   - For each dependency issue, verify CVE via official sources. If unverifiable, mark as unknown.
+   - Run validators. Report any failures.
+
+4. **APPROVAL GATE BEFORE FIXES**
+   - Present all findings with severity, CVSS, and proposed fixes to the user via `vscode/askQuestions`.
+   - Separate high/critical vs low/medium, and require explicit approval for each group before making code changes.
+   - For any vulnerability requiring major refactor, propose via `vscode/askQuestions` and get approval first.
+
+5. **REMEDIATION & FIXING**
+   - Create/checkout a branch for security fixes (e.g., `security/fix-auth-bypass`).
+   - Apply only approved fixes.
+   - Fix low/medium vulnerabilities as approved.
+   - For high/critical, apply only after explicit approval from step 4.
+   - **Security Regression:** Re-run the specific scan (e.g., `gitleaks` or `npm audit`) to prove the vulnerability is actually resolved, if tools available.
+   - Run functional tests to ensure no regressions, if configured. Report limitations if not run.
+
+6. **REPORTING & TRACEABILITY**
+   - Generate a versioned `.sdrive/reports/security/security-audit-{scope}-{date}.md` using the template below.
+   - Redact all secrets.
+   - If feature-scoped, update `.sdrive/governance/<feature>/traceability.json` only for security NFR rows, preserving all other rows.
+   - Present the report to the user.
+
+7. **COMMIT & PUSH (After Second Approval)**
+   - Ask user via `vscode/askQuestions`: "Approve committing and pushing these security fixes?"
+   - Commit with security-focused messages: `fix(sec): patch XSS vulnerability in user profile (CVSS 7.5)`.
+   - Push to the security branch.
+</workflow>
+
+<audit-template>
+Use this exact structure for the versioned security report:
+
+# Security Audit Report: [Scope/Feature Name]
+
+## 1. Executive Summary
+- **Date:** [DATE]
+- **Auditor:** AI Security Agent
+- **Overall Risk Level:** [Critical/High/Medium/Low]
+- **Total Vulnerabilities Found:** [X] (Critical: [X], High: [X], Med: [X], Low: [X])
+
+## 2. Threat Model Summary
+- **Key Assets:** [List]
+- **Trust Boundaries:** [List]
+
+## 3. Vulnerability Details
+### [VULN-001]: [Vulnerability Title]
+- **CVSS Score:** [X.X] ([Severity])
+- **Location:** [File:Line or Dependency:Version]
+- **Description:** [Brief description of the flaw]
+- **Impact:** [What an attacker could achieve]
+- **Remediation:** [How it was fixed or recommended fix]
+- **Status:** [Fixed / Open / Deferred]
+
+*(Repeat for all vulnerabilities. NEVER include actual secret values in this report.)*
+
+## 4. Security Regression Verification
+- [ ] Dependency audit passed. *(Only if actually run)*
+- [ ] Secret scan passed. *(Only if actually run)*
+- [ ] Functional tests passed. *(Only if actually run)*
+- **Limitations:** [State if any of the above were not automatically verified.]
+
+## 5. Recommendations
+- [List strategic security improvements for the future]
+</audit-template>
+
+<definition-of-done>
+The security audit phase is NOT complete until:
+- [ ] Constitution read, or fallback handled.
+- [ ] Feature/governance files read, or fallback handled.
+- [ ] Threat model documented.
+- [ ] All fixes approved before application.
+- [ ] Security regression checks actually run or limitations reported.
+- [ ] Redacted security report generated with CVSS scores and versioned filename.
+- [ ] Traceability updated only for security NFR rows.
+- [ ] Commit/push only after explicit user approval.
+- [ ] Validation failures, if any, reported honestly.
+</definition-of-done>
+
+<deliverables>
+At the end of your work, provide:
+1. ✅ Fixed vulnerabilities in codebase on a dedicated security branch.
+2. ✅ Updated dependencies (if safe and approved).
+3. ✅ Versioned `security-audit-{scope}-{date}.md` with CVSS scores and redacted secrets.
+4. ✅ Confirmation of security regression and functional test results, with limitations disclosed.
+5. ✅ Updated `.sdrive/governance/<feature>/traceability.json` only for security NFR rows.
+</deliverables>

package/commands/gates.js

@@ -0,0 +1,64 @@
+const fs = require("fs");
+const path = require("path");
+
+const projectRoot = process.cwd();
+
+function getWorkflowState() {
+  const workflowStatePath = path.join(projectRoot, ".sdrive", "workflow-state.json");
+
+  if (!fs.existsSync(workflowStatePath)) {
+    console.error("❌ workflow-state.json not found.");
+    process.exit(1);
+  }
+
+  return JSON.parse(fs.readFileSync(workflowStatePath, "utf8"));
+}
+
+function saveWorkflowState(state) {
+  const workflowStatePath = path.join(projectRoot, ".sdrive", "workflow-state.json");
+  fs.writeFileSync(workflowStatePath, JSON.stringify(state, null, 2));
+}
+
+function approveGate(featureName, gate) {
+  const state = getWorkflowState();
+
+  const feature = state.features?.find((f) => f.name === featureName);
+
+  if (!feature) {
+    console.error(`❌ Feature "${featureName}" not found.`);
+    process.exit(1);
+  }
+
+  if (!feature.gates) {
+    feature.gates = {};
+  }
+
+  feature.gates[gate] = "approved";
+
+  feature.history = feature.history || [];
+  feature.history.push({
+    event: `${gate}_approved`,
+    timestamp: new Date().toISOString()
+  });
+
+  saveWorkflowState(state);
+  console.log(`✅ Gate "${gate}" approved for feature "${featureName}".`);
+}
+
+function gateStatus(featureName, gate) {
+  const state = getWorkflowState();
+  const feature = state.features?.find((f) => f.name === featureName);
+
+  if (!feature) {
+    return "unknown";
+  }
+
+  return feature.gates?.[gate] || "pending";
+}
+
+module.exports = {
+  approveGate,
+  gateStatus,
+  getWorkflowState,
+  saveWorkflowState
+};

package/commands/manifest.json

@@ -0,0 +1,96 @@
+{
+  "prefix": "/sdrive:",
+  "version": "1.0.0",
+  "commands": [
+    {
+      "command": "/sdrive:constitution",
+      "agent": "constitution",
+      "agentFile": ".sdrive/agents/01-constitution.md",
+      "description": "Initialize or update the project constitution",
+      "acceptsFeature": false,
+      "gates": ["constitution"],
+      "validators": ["governance"]
+    },
+    {
+      "command": "/sdrive:propose",
+      "agent": "specification",
+      "agentFile": ".sdrive/agents/02-specification.md",
+      "description": "Create feature specification, traceability, technical plan, and tasks",
+      "acceptsFeature": true,
+      "gates": ["specification", "planning"],
+      "validators": ["governance"]
+    },
+    {
+      "command": "/sdrive:design",
+      "agent": "uiux",
+      "agentFile": ".sdrive/agents/03-uiux.md",
+      "description": "Build UI/UX prototype and design system",
+      "acceptsFeature": true,
+      "gates": [],
+      "validators": ["governance"]
+    },
+    {
+      "command": "/sdrive:sync",
+      "agent": "cascade",
+      "agentFile": ".sdrive/agents/04-cascade.md",
+      "description": "Sync spec, plan, tasks, and traceability",
+      "acceptsFeature": true,
+      "gates": [],
+      "validators": ["governance"]
+    },
+    {
+      "command": "/sdrive:skills",
+      "agent": "discover-skills",
+      "agentFile": ".sdrive/agents/05-discover-skills.md",
+      "description": "Audit and manage AI skills",
+      "acceptsFeature": false,
+      "gates": [],
+      "validators": []
+    },
+    {
+      "command": "/sdrive:docs",
+      "agent": "documentation",
+      "agentFile": ".sdrive/agents/06-documentation.md",
+      "description": "Generate documentation and detect drift",
+      "acceptsFeature": true,
+      "gates": [],
+      "validators": ["governance"]
+    },
+    {
+      "command": "/sdrive:apply",
+      "agent": "implementation",
+      "agentFile": ".sdrive/agents/07-implementation.md",
+      "description": "Write production code from approved tasks",
+      "acceptsFeature": true,
+      "gates": ["implementation"],
+      "validators": ["governance"]
+    },
+    {
+      "command": "/sdrive:performance",
+      "agent": "performance",
+      "agentFile": ".sdrive/agents/08-performance.md",
+      "description": "Benchmark and optimize performance",
+      "acceptsFeature": true,
+      "gates": [],
+      "validators": ["governance"]
+    },
+    {
+      "command": "/sdrive:review",
+      "agent": "review-complete",
+      "agentFile": ".sdrive/agents/09-review-complete.md",
+      "description": "Final audit, merge, and archive",
+      "acceptsFeature": true,
+      "gates": ["review"],
+      "validators": ["governance"]
+    },
+    {
+      "command": "/sdrive:secure",
+      "agent": "security",
+      "agentFile": ".sdrive/agents/10-security.md",
+      "description": "Security audit, threat modeling, and fixes",
+      "acceptsFeature": true,
+      "gates": [],
+      "validators": ["governance"]
+    }
+  ]
+}

package/commands/router.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { getWorkflowState, saveWorkflowState } = require("./gates");
+
+const projectRoot = process.cwd();
+
+function loadManifest() {
+  const manifestPath = path.join(projectRoot, ".sdrive", "commands", "manifest.json");
+
+  if (!fs.existsSync(manifestPath)) {
+    console.error("❌ manifest.json not found. Run `sdrive init` first.");
+    process.exit(1);
+  }
+
+  return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+}
+
+function findCommand(commandName) {
+  const manifest = loadManifest();
+  return manifest.commands.find((cmd) => cmd.command === commandName);
+}
+
+function loadAgent(agentFile) {
+  const agentPath = path.join(projectRoot, agentFile);
+
+  if (!fs.existsSync(agentPath)) {
+    console.error(`❌ Agent file not found: ${agentFile}`);
+    process.exit(1);
+  }
+
+  return fs.readFileSync(agentPath, "utf8");
+}
+
+function runValidators(validators) {
+  const validatorPath = path.join(projectRoot, ".sdrive", "scripts", "validate-governance.js");
+
+  if (!validators || validators.length === 0) {
+    return true;
+  }
+
+  if (!fs.existsSync(validatorPath)) {
+    console.warn("⚠️  Validator script not found. Skipping validation.");
+    return true;
+  }
+
+  try {
+    execSync(`node "${validatorPath}"`, { stdio: "inherit" });
+    return true;
+  } catch (error) {
+    console.error("❌ Validation failed.");
+    return false;
+  }
+}
+
+function checkGate(featureName, gate) {
+  const state = getWorkflowState();
+  const feature = state.features?.find((f) => f.name === featureName);
+
+  if (!feature) {
+    console.error(`❌ Feature "${featureName}" not found.`);
+    return false;
+  }
+
+  return feature.gates?.[gate] === "approved";
+}
+
+function approveGate(featureName, gate) {
+  const state = getWorkflowState();
+  const feature = state.features?.find((f) => f.name === featureName);
+
+  if (!feature) {
+    console.error(`❌ Feature "${featureName}" not found.`);
+    return false;
+  }
+
+  if (!feature.gates) {
+    feature.gates = {};
+  }
+
+  feature.gates[gate] = "approved";
+
+  feature.history = feature.history || [];
+  feature.history.push({
+    event: `${gate}_approved`,
+    timestamp: new Date().toISOString()
+  });
+
+  saveWorkflowState(state);
+  console.log(`✅ Gate "${gate}" approved for feature "${featureName}".`);
+  return true;
+}
+
+function toKebabCase(text) {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function main() {
+  const commandName = process.argv[2];
+  const rawFeature = process.argv[3];
+
+  if (!commandName) {
+    console.error("❌ Usage: node router.js /sdrive:<command> [feature-description]");
+    process.exit(1);
+  }
+
+  const command = findCommand(commandName);
+
+  if (!command) {
+    console.error(`❌ Unknown command: ${commandName}`);
+    process.exit(1);
+  }
+
+  let featureName = null;
+
+  if (rawFeature) {
+    featureName = toKebabCase(rawFeature);
+    console.log(`\n📦 Feature: ${featureName}`);
+  }
+
+  console.log(`\n🚀 SpecDrive Command: ${command.command}`);
+  console.log(`📄 Agent: ${command.agent}`);
+  console.log(`📁 Agent File: ${command.agentFile}`);
+  console.log(`📝 Description: ${command.description}`);
+
+  // Gate enforcement
+  if (command.gates && command.gates.length > 0) {
+    if (!featureName) {
+      console.error(`❌ This command requires a feature name or description.`);
+      console.error(`   Usage: node router.js ${commandName} "<feature-description>"`);
+      process.exit(1);
+    }
+
+    console.log(`\n🚧 Required Gates: ${command.gates.join(", ")}`);
+
+    for (const gate of command.gates) {
+      if (!checkGate(featureName, gate)) {
+        console.log(`\n⏸️  Gate "${gate}" is NOT approved for "${featureName}".`);
+        console.log(`   Please approve this gate before running this command.`);
+        console.log(`   Use: sdrive approve ${gate}\n`);
+        process.exit(1);
+      }
+      console.log(`✅ Gate "${gate}" is approved.`);
+    }
+  }
+
+  const agentContent = loadAgent(command.agentFile);
+  console.log(`\n✅ Loaded agent instructions (${agentContent.length} characters).`);
+
+  const valid = runValidators(command.validators);
+
+  if (!valid) {
+    console.error("\n❌ Command execution blocked due to validation failure.");
+    process.exit(1);
+  }
+
+  console.log("\n🤖 The AI tool should now read the agent instructions and execute the command.");
+  console.log("⏸️  Remember to stop for human approval after the command completes.\n");
+}
+
+main();

package/commands/tools.json

@@ -0,0 +1,25 @@
+{
+  "version": "1.0.0",
+  "tools": [
+    {
+      "name": "github-copilot",
+      "adapterPath": ".github/copilot-instructions.md"
+    },
+    {
+      "name": "cline",
+      "adapterPath": ".clinerules/sdrive.md"
+    },
+    {
+      "name": "claude-code",
+      "adapterPath": ".claude/commands/sdrive.md"
+    },
+    {
+      "name": "cursor",
+      "adapterPath": ".cursor/rules/sdrive.md"
+    },
+    {
+      "name": "vscode-native",
+      "adapterPath": ".vscode/sdrive-commands.json"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "specdrive-cli",
+  "version": "0.1.0",
+  "description": "SpecDrive enterprise spec-driven development CLI",
+  "bin": {
+    "sdrive": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "scripts/",
+    "commands/",
+    "schemas/",
+    "agents/"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "ajv": "^8.12.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "spec-driven",
+    "ai",
+    "governance",
+    "cli",
+    "specflow"
+  ],
+  "license": "MIT"
+}

package/schemas/plan.schema.json

@@ -0,0 +1,89 @@
+{
+  "": "http://json-schema.org/draft-07/schema#",
+  "title": "Technical Plan",
+  "type": "object",
+  "properties": {
+    "feature": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+    "version": { "type": "integer", "minimum": 1 },
+    "architecture": {
+      "type": "object",
+      "properties": {
+        "approach": { "type": "string" },
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "action": { "enum": ["create", "modify", "reuse", "delete"] },
+              "description": { "type": "string" }
+            },
+            "required": ["name", "action"]
+          }
+        }
+      },
+      "required": ["approach", "components"]
+    },
+    "dataModel": {
+      "type": "object",
+      "properties": {
+        "entities": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "action": { "enum": ["create", "update", "no_change", "delete"] },
+              "fields": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "name": { "type": "string" },
+                    "type": { "type": "string" },
+                    "nullable": { "type": "boolean" },
+                    "action": { "enum": ["add", "modify", "remove", "no_change"] }
+                  },
+                  "required": ["name", "type", "action"]
+                }
+              }
+            },
+            "required": ["name", "action", "fields"]
+          }
+        },
+        "flowDescription": { "type": "string" }
+      },
+      "required": ["entities", "flowDescription"]
+    },
+    "apiContracts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "method": { "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] },
+          "path": { "type": "string" },
+          "action": { "enum": ["create", "modify", "reuse", "delete"] },
+          "authenticationRequired": { "type": "boolean" },
+          "linkedRequirements": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^(FR|NFR)-[0-9]{3}$" }
+          }
+        },
+        "required": ["method", "path", "action", "linkedRequirements"]
+      }
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "type": { "enum": ["library", "service", "internal", "external"] },
+          "action": { "enum": ["add", "update", "remove", "no_change"] }
+        },
+        "required": ["name", "type", "action"]
+      }
+    }
+  },
+  "required": ["feature", "version", "architecture", "dataModel"]
+}