@onuraslan/sdd 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onur ASLAN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# SDD Plugin Suite
+
+**Spec-driven development from planning to implementation.**
+
+This repository is a collection of skills that automate software development workflows using Spec-Driven Development (SDD). Designed for developers and QA engineers who want structured, adaptive workflows without rigid templates.
+
+---
+
+## Installation
+
+You can install SDD in two ways:
+
+### Option 1: npm package installation (recommended)
+
+Install the package and run the interactive installer from the npm bundle itself:
+
+```bash
+npx @onuraslan/sdd install
+```
+
+This installer reads the skill content from the installed npm package and copies it directly to the target agent directory. It does not clone the GitHub repository at runtime.
+
+### Option 2: Claude Code plugin marketplace
+
+```bash
+/plugin marketplace add https://github.com/onur-aslan/sdd
+```
+
+### Option 3: skills.sh installer
+
+If you want to copy the skills into your project for local editing and customization, you can also install them with `skills.sh`:
+
+```bash
+npx skills@latest add onuraslan/sdd
+```
+
+> The npm package route is the recommended runtime distribution path for the installer. The repository is kept as the source of truth for publishing and release management.
+---
+
+## Plugins
+
+| Plugin | Description |
+|--------|-------------|
+| [**SDD Core**](sdd/) | Automated workflows from spec design to implementation |
+| [**SDD Frontend**](sdd-frontend/) | Frontend-specific skills for UI design, enhancement, and testing |
+| [**SDD Backend**](sdd-backend/) | Backend development skills for API, database, and server-side logic |
+| [**SDD Utility**](sdd-utilty/) | Code quality analysis, gap analysis, session handoff, and glossary |
+
+---
+
+## SDD Core Plugin
+
+Automated workflows that guide you from specification to implementation. The **workflow-gateway** skill selects the right workflow based on your task type.
+
+### Getting Started
+
+**1. Run workflow-generator to select your workflow:**
+
+```bash
+/workflow-generator
+```
+
+This will:
+- Ask you to choose: Feature Development, Bug Fix, Enhancement, or Help me decide
+- Detect if it's Backend, Frontend, or Both
+- Write the selected workflow to `docs/workflow.md`
+
+**2. Follow the steps in `docs/workflow.md`:**
+
+Each workflow file contains a sequence of skills to run in order. Run them one by one:
+
+---
+
+### Workflows
+
+#### 1. Feature Development (Frontend)
+
+```
+deep-spec -> spec-to-prd -> [small scope: implementer] | [large PRD: prd-to-task -> feature-implementer] -> feature-e2e-verifier -> prd-test-writer -> gap-analysis -> code-slop-review
+```
+
+#### 2. Feature Development (Backend)
+
+```
+deep-spec -> spec-to-prd -> [small scope: implementer -> verify-with-curl] | [large PRD: prd-to-task -> chicago-tdd (per task)] -> feature-e2e-verifier -> prd-test-writer -> gap-analysis -> code-slop-review
+```
+
+#### 3. Bug Fix
+
+```
+bug-fix-frontend|backend -> verify-with-playwright-mcp|verify-with-curl
+```
+
+#### 4. Enhancement
+
+```
+frontend|backend-enhancement -> verify-with-playwright-mcp|verify-with-curl
+```
+
+### Core Skills
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| `workflow-generator` | `/workflow-generator` | Entry point -- selects workflow, writes `docs/workflow.md` |
+| `deep-spec` | `/deep-spec` | Interview-driven spec creation |
+| `spec-to-prd` | `/spec-to-prd` | Convert spec.md to PRD |
+| `prd-to-task` | `/prd-to-task` | Split PRD into tasks with Gherkin scenarios |
+| `implementer` | `/implementer` | Implement from conversation context (no files needed) |
+| `feature-implementer` | `/feature-implementer <feature.md>` | Implement tasks sequentially |
+| `chicago-tdd` | `/chicago-tdd <task.md>` | TDD for a single task (Red-Green-Refactor) |
+| `prd-test-writer` | `/prd-test-writer <prd.md>` | Write acceptance tests in parallel |
+| `feature-e2e-verifier` | `/feature-e2e-verifier <prd.md>` | E2E verify User Stories |
+
+---
+
+## SDD Frontend Plugin
+
+Frontend-specific skills for UI design, enhancement, and verification.
+
+### Core Skills
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| `frontend-enhancement` | `/frontend-enhancement` | Interview-driven UI enhancement with ASCII mockup planning |
+| `bug-fix-frontend` | `/bug-fix-frontend "<description>"` | Senior-level frontend bug fixing with auto-verification |
+| `feature-e2e-verifier` | `/feature-e2e-verifier <prd.md>` | E2E verify User Stories by testing all Acceptance Criteria sequentially |
+| `verify-with-playwright-mcp` | `/verify-with-playwright-mcp` | Visual verification with auto-fix loop |
+| `using-playwright-mcp` | `/using-playwright-mcp` | General-purpose Playwright browser automation |
+| `git-cleanup-playwright-artifacts` | `/git-cleanup-playwright-artifacts` | Clean up Playwright screenshots and test artifacts |
+
+---
+
+## SDD Backend Plugin
+
+Backend development skills for API, database, and server-side logic with unit testing.
+
+### Core Skills
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| `bug-fix-backend` | `/bug-fix-backend` | Fix backend bugs |
+| `backend-enhancement` | `/backend-enhancement` | Enhance backend features |
+| `verify-with-curl` | `/verify-with-curl` | Verify APIs with curl requests |
+
+---
+
+## SDD Utility Plugin
+
+Code quality and session management utilities.
+
+### Core Skills
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| `code-slop-review` | `/code-slop-review` | 5-layer code quality analysis |
+| `gap-analysis` | `/gap-analysis` | Compare implementation against requirements |
+| `glossary-builder` | `/glossary-builder` | Build domain glossary for project |
+| `using-glossary` | `/using-glossary` | Use glossary for consistent terminology |
+| `ask-first` | `/ask-first` | Plan before implement — pause for approval on non-trivial tasks |
+| `handoff` | `/handoff` | Capture session knowledge for the next skill |
+| `handoff-resume` | `/handoff-resume` | Resume session from handoff file |
+| `init-feature` | `/init-feature` | Initialize a new feature |
+
+### Handoff Workflow
+
+Use this 3-step workflow to transfer session knowledge between sessions:
+
+```
+/handoff -> /clear -> /handoff-resume
+```
+
+1. **`/handoff`** — Captures current session context, decisions, and progress into a handoff file.
+2. **`/clear`** — Clears the conversation history to start fresh.
+3. **`/handoff-resume`** — Loads the handoff file and restores session context for the next skill.
+
+---
+
+## License
+
+MIT
+
+## Author
+
+Onur ASLAN

package/bin/sdd.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { run } from '../cli/index.js';
+
+const result = await run(process.argv.slice(2));
+
+if (typeof result === 'string') {
+  process.stdout.write(`${result}\n`);
+}

package/cli/index.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import readline from 'node:readline/promises';
+
+import { installSelectedSkills } from './install.js';
+import { getSkillGroups } from './skills.js';
+import { askInteractiveInstall } from './prompts.js';
+
+const packageJsonPath = fileURLToPath(new URL('../package.json', import.meta.url));
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+function formatHelp() {
+  return `SDD - Spec Driven Development\n\nUsage:\n  sdd <command>\n\nCommands:\n  install     Install SDD skills\n  list        Show installed SDD skills\n  update      Update SDD installation\n  doctor      Diagnose SDD installation\n\nOptions:\n  --help\n  --version`;
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    return formatHelp();
+  }
+
+  if (argv.includes('--version') || argv.includes('-v')) {
+    return packageJson.version;
+  }
+
+  if (argv.length === 0) {
+    return formatHelp();
+  }
+
+  const [command, ...rest] = argv;
+
+  if (command === 'install') {
+    const args = rest;
+
+    if (process.stdin.isTTY && !args.includes('--non-interactive')) {
+      const options = await askInteractiveInstall();
+      const result = await installSelectedSkills({
+        targetId: options.targetId,
+        plugins: options.plugins,
+        scope: options.scope,
+        version: packageJson.version
+      });
+
+      return `Installed ${result.installedCount} skills to ${result.installRoot}.`;
+    }
+
+    const requestedTargets = args.includes('--all') ? Object.keys(getSkillGroups()) : ['core'];
+    const targetId = args.includes('--target') ? args[args.indexOf('--target') + 1] : 'claude';
+    const scope = args.includes('--user') ? 'user' : 'project';
+
+    const result = await installSelectedSkills({
+      targetId,
+      plugins: requestedTargets,
+      scope,
+      version: packageJson.version
+    });
+
+    return `Installed ${result.installedCount} skills to ${result.installRoot}.`;
+  }
+
+  if (command === 'list') {
+    return `SDD ${packageJson.version}\nInstalled targets:\nClaude Code`;
+  }
+
+  if (command === 'update') {
+    return 'Update support is not implemented yet.';
+  }
+
+  if (command === 'doctor') {
+    return 'Doctor support is not implemented yet.';
+  }
+
+  return `${formatHelp()}\n\nUnknown command: ${command}`;
+}

package/cli/install.js

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getPackageSkillsRoot, getSkillGroups, getSkillsForGroup } from './skills.js';
+import { resolveTargetPath } from './targets.js';
+
+function ensureDirectory(targetPath) {
+  fs.mkdirSync(targetPath, { recursive: true });
+}
+
+function writeMetadata(metadataPath, targetId, plugins, version) {
+  const metadata = {
+    version,
+    plugins,
+    installedAt: new Date().toISOString()
+  };
+
+  fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+}
+
+function writeMcpConfig(target, selectedPlugins) {
+  if (!selectedPlugins.includes('frontend')) {
+    return;
+  }
+
+  const { mcpConfigPath, mcpFormat } = target;
+  const playwrightConfig = {
+    command: 'npx',
+    args: ['@playwright/mcp']
+  };
+
+  if (mcpFormat === 'toml') {
+    const dir = path.dirname(mcpConfigPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const existing = fs.existsSync(mcpConfigPath)
+      ? fs.readFileSync(mcpConfigPath, 'utf8')
+      : '';
+    const lines = existing.trim() ? existing.trim().split('\n') : [];
+    const section = '[mcp_servers.playwright]';
+    const block = [
+      section,
+      'command = "npx"',
+      'args = ["@playwright/mcp"]'
+    ];
+
+    const filtered = lines.filter((line) => !line.startsWith('[mcp_servers.playwright]') && !line.startsWith('command = ') && !line.startsWith('args = '));
+    const nextContent = [...filtered, '', ...block, ''].join('\n');
+    fs.writeFileSync(mcpConfigPath, `${nextContent}\n`, 'utf8');
+    return;
+  }
+
+  if (mcpFormat === 'json-opencode') {
+    const existing = fs.existsSync(mcpConfigPath)
+      ? JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8'))
+      : {};
+
+    const nextConfig = {
+      ...existing,
+      mcp: {
+        ...(existing.mcp || {}),
+        playwright: {
+          type: 'stdio',
+          command: 'npx',
+          args: ['@playwright/mcp']
+        }
+      }
+    };
+
+    fs.writeFileSync(mcpConfigPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf8');
+    return;
+  }
+
+  const existing = fs.existsSync(mcpConfigPath)
+    ? JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8'))
+    : {};
+
+  const nextConfig = {
+    ...existing,
+    mcpServers: {
+      ...(existing.mcpServers || {}),
+      playwright: playwrightConfig
+    },
+    playwright: playwrightConfig
+  };
+
+  const dir = path.dirname(mcpConfigPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(mcpConfigPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf8');
+}
+
+export async function installSelectedSkills({
+  targetId = 'claude',
+  plugins = Object.keys(getSkillGroups()),
+  scope = 'project',
+  cwd = process.cwd(),
+  version = '1.0.2',
+  conflictHandler = null
+}) {
+  const selected = Array.isArray(plugins) ? plugins : [plugins];
+  const consistentPlugins = selected.filter(Boolean);
+  const target = resolveTargetPath(targetId, scope, cwd);
+
+  ensureDirectory(target.installRoot);
+  let installedCount = 0;
+
+  for (const pluginId of consistentPlugins) {
+    const pluginConfig = getSkillGroups()[pluginId];
+    if (!pluginConfig) {
+      throw new Error(`Plugin "${pluginId}" is missing from this package. The installation cannot continue.`);
+    }
+
+    const groupDirectory = path.join(pluginConfig.pluginRoot, 'skills');
+    if (!fs.existsSync(groupDirectory)) {
+      throw new Error(`Plugin "${pluginId}" is missing from this package. The installation cannot continue.`);
+    }
+
+    const skills = getSkillsForGroup(pluginId);
+
+    for (const skillName of skills) {
+      const source = path.join(groupDirectory, skillName);
+      const destination = path.join(target.installRoot, skillName);
+
+      if (fs.existsSync(destination)) {
+        if (conflictHandler) {
+          const action = await conflictHandler({ skillName, destination, source, pluginId });
+          if (action === 'skip') {
+            continue;
+          }
+          if (action === 'abort') {
+            throw new Error(`Installation aborted while processing Skill: ${skillName}`);
+          }
+          if (action === 'overwrite') {
+            fs.rmSync(destination, { recursive: true, force: true });
+          }
+        } else {
+          throw new Error(`Skill already exists: ${skillName}`);
+        }
+      }
+
+      fs.cpSync(source, destination, { recursive: true, force: true });
+      installedCount += 1;
+    }
+  }
+
+  writeMetadata(target.metadataPath, targetId, consistentPlugins, version);
+  writeMcpConfig(target, consistentPlugins);
+
+  return {
+    installedCount,
+    targetId,
+    plugins: consistentPlugins,
+    scope,
+    installRoot: target.installRoot,
+    metadataPath: target.metadataPath,
+    mcpConfigPath: target.mcpConfigPath
+  };
+}

package/cli/prompts.js

@@ -0,0 +1,98 @@
+import readline from 'node:readline/promises';
+import { targets } from './targets.js';
+import { getSkillGroups } from './skills.js';
+
+export async function promptTarget(rl) {
+  const targetEntries = Object.values(targets);
+
+  console.log('\nSelect target:');
+  targetEntries.forEach((target, index) => {
+    console.log(`${index + 1}. ${target.name}`);
+  });
+
+  const answer = await rl.question('Choose a target [1-5]: ');
+  const index = Number.parseInt(answer, 10) - 1;
+
+  if (!Number.isInteger(index) || index < 0 || index >= targetEntries.length) {
+    throw new Error('Unknown installation target.');
+  }
+
+  return targetEntries[index].id;
+}
+
+export async function promptPluginSelection(rl) {
+  const groups = Object.values(getSkillGroups());
+
+  console.log('\nSelect plugins:');
+  groups.forEach((group, index) => {
+    console.log(`${index + 1}. ${group.name}`);
+  });
+
+  const answer = await rl.question('Choose plugin numbers separated by commas (or "all"): ');
+  const normalized = answer.trim().toLowerCase();
+
+  if (normalized === 'all') {
+    return groups.map((group) => group.id);
+  }
+
+  const selected = new Set();
+
+  for (const value of normalized.split(',')) {
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    const index = Number.parseInt(trimmed, 10) - 1;
+    if (!Number.isInteger(index) || index < 0 || index >= groups.length) {
+      throw new Error(`Unknown plugin selection: ${trimmed}`);
+    }
+    selected.add(groups[index].id);
+  }
+
+  if (selected.size === 0) {
+    return [groups[0].id];
+  }
+
+  return [...selected];
+}
+
+export async function promptScope(rl) {
+  console.log('\nWhere should SDD be installed?');
+  console.log('1. Current project');
+  console.log('2. User home directory');
+  const answer = await rl.question('Choose a location [1-2]: ');
+  const value = Number.parseInt(answer, 10);
+
+  if (value === 2) {
+    return 'user';
+  }
+
+  return 'project';
+}
+
+export async function promptConfirmation(rl, targetId, plugins, scope) {
+  console.log(`\nInstalling SDD for ${targets[targetId].name} (${scope})`);
+  console.log(`Plugins: ${plugins.join(', ')}`);
+  const answer = await rl.question('Proceed? [Y/n]: ');
+  return answer.trim().toLowerCase() !== 'n';
+}
+
+export async function askInteractiveInstall() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    const targetId = await promptTarget(rl);
+    const plugins = await promptPluginSelection(rl);
+    const scope = await promptScope(rl);
+    const confirmed = await promptConfirmation(rl, targetId, plugins, scope);
+
+    if (!confirmed) {
+      throw new Error('Installation cancelled.');
+    }
+
+    return { targetId, plugins, scope };
+  } finally {
+    rl.close();
+  }
+}

package/cli/skills.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+
+export const skillGroups = {
+  core: {
+    id: 'core',
+    name: 'Core',
+    pluginRoot: path.join(packageRoot, 'sdd')
+  },
+  frontend: {
+    id: 'frontend',
+    name: 'Frontend',
+    pluginRoot: path.join(packageRoot, 'sdd-frontend')
+  },
+  backend: {
+    id: 'backend',
+    name: 'Backend',
+    pluginRoot: path.join(packageRoot, 'sdd-backend')
+  },
+  utility: {
+    id: 'utility',
+    name: 'Utility',
+    pluginRoot: path.join(packageRoot, 'sdd-utility')
+  }
+};
+
+export function getSkillGroups() {
+  return { ...skillGroups };
+}
+
+export function getPackageSkillsRoot() {
+  return packageRoot;
+}
+
+export function getSkillsForGroup(groupId) {
+  const group = skillGroups[groupId];
+
+  if (!group) {
+    return [];
+  }
+
+  const groupDirectory = path.join(group.pluginRoot, 'skills');
+
+  if (!fs.existsSync(groupDirectory)) {
+    throw new Error(`Plugin "${groupId}" is missing from this package.`);
+  }
+
+  return fs
+    .readdirSync(groupDirectory, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}

package/cli/targets.js

@@ -0,0 +1,69 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export const targets = {
+  claude: {
+    id: 'claude',
+    name: 'Claude Code',
+    skillDirectory: '.claude/skills',
+    mcpConfigPath: '.mcp.json',
+    mcpFormat: 'json'
+  },
+  cursor: {
+    id: 'cursor',
+    name: 'Cursor',
+    skillDirectory: '.cursor/skills',
+    mcpConfigPath: '.cursor/mcp.json',
+    mcpFormat: 'json'
+  },
+  codex: {
+    id: 'codex',
+    name: 'Codex',
+    skillDirectory: '.codex/skills',
+    mcpConfigPath: '.codex/config.toml',
+    mcpFormat: 'toml'
+  },
+  windsurf: {
+    id: 'windsurf',
+    name: 'Windsurf',
+    skillDirectory: '.windsurf/skills',
+    mcpConfigPath: '.windsurf/mcp.json',
+    mcpFormat: 'json'
+  },
+  opencode: {
+    id: 'opencode',
+    name: 'OpenCode',
+    skillDirectory: '.opencode/skills',
+    mcpConfigPath: 'opencode.json',
+    mcpFormat: 'json-opencode'
+  }
+};
+
+export function resolveInstallBase(scope = 'project', cwd = process.cwd()) {
+  if (scope === 'user') {
+    return os.homedir();
+  }
+
+  return cwd;
+}
+
+export function resolveTargetPath(targetId, scope = 'project', cwd = process.cwd()) {
+  const target = targets[targetId];
+
+  if (!target) {
+    throw new Error(`Unknown installation target: ${targetId}`);
+  }
+
+  const baseDir = resolveInstallBase(scope, cwd);
+  const installRoot = path.resolve(baseDir, target.skillDirectory);
+  const metadataPath = path.resolve(baseDir, path.dirname(target.skillDirectory), 'sdd.json');
+  const mcpConfigPath = path.resolve(baseDir, target.mcpConfigPath);
+
+  return {
+    ...target,
+    baseDir,
+    installRoot,
+    metadataPath,
+    mcpConfigPath
+  };
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@onuraslan/sdd",
+  "version": "1.0.5",
+  "type": "module",
+  "description": "Spec-Driven Development skill package and interactive installer for AI coding agents.",
+  "license": "MIT",
+  "bin": {
+    "sdd": "bin/sdd.js"
+  },
+  "files": [
+    "bin",
+    "cli",
+    "sdd",
+    "sdd-backend",
+    "sdd-frontend",
+    "sdd-utility",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
+}